REST API¶

In this page we cover the general structure of the API resources, the supported request types, and expected responses.

For convenience, Application Manager ships with an OpenAPI 2.0 specification and Swagger web client:

OpenAPI 2.0 specification: https://appmgr:8080/swagger.json
Swagger web client: http://appmgr:8080/swagger

Both the OpenAPI specification and Swagger web client are not supported and are provided on an as-is basis.

More information on accessing Application Manager.

Verbs
- GET
- POST
- PATCH
- DELETE
Resource Objects
Content-Types
Resource Versions
API Versioning
Responses

Verbs ¶

Application Manager uses the traditional HTTP verbs for CRUD operations on resources. Currently, there is no support for PUT requests.

GET ¶

List resources or request a single resource.

For non-namespaced resources:

GET /api/v1/<resourcePlural>

GET /api/v1/<resourcePlural>/<resourceId>

GET /api/v1/<resourcePlural>/<resourceName>

For namespaced resources:

GET /api/v1/namespaces/<namespaceName>/<resourcePlural>

GET /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceId>

GET /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceName>

POST ¶

Create a resource.

For non-namespaced resources:

POST /api/v1/<resourcePlural>

For namespaced resources:

POST /api/v1/namespaces/<namespaceName>/<resourcePlural>

PATCH ¶

Selectively modify an existing resource.

For non-namespaced resources:

PATCH /api/v1/<resourcePlural>/<resourceId>

PATCH /api/v1/<resourcePlural>/<resourceName>

For namespaced resources:

PATCH /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceId>

PATCH /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceName>

Patch requests follow RFC 7386 by default. Specified attributes in the patch request are merged with existing attributes. If you want to remove an attribute, you specify null.

As an example, the following request will remove the foo entry and add bar: baz to flinkConfiguration of a Deployment.

spec:
  template:
    spec:
      flinkConfiguration:
        foo: null
        bar: baz

DELETE ¶

Delete a resource.

For non-namespaced resources:

DELETE /api/v1/<resourcePlural>/<resourceId>

DELETE /api/v1/<resourcePlural>/<resourceName>

For namespaced resources:

DELETE /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceId>

DELETE /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceName>

Note that you can only delete resources that are managed by users. Furthermore, certain resources will require the resource to be in a certain state before you can actually delete them (for instance a Deployment cannot be in state running when you try to delete it) or delete other sub-resources (for instance deleting a namespace will delete all it’s contained sub-resources).

Resource Objects ¶

Names ¶

Resources that can be addressed by name require their names to be unique within a namespace and immutable. A name is only allowed to include the following characters:

a-z, A-Z
0-9
_, -

Examples:

resource-name-01
resource_name-02

Single Objects ¶

Each managed resource object has the following structure:

kind: ResourceKind
apiVersion: v1
metadata:
  ...
spec:
  ...
status:
  ...

The metadata and spec parts of resources are managed by users whereas the status is fully managed by the system.

List Objects ¶

List objects are returned via a List wrapper kind that holds objects in an items array, e.g. when listing deployments you will receive a resource of kind DeploymentList with each Deployment being part of the items array.

kind: KindList
apiVersion: v1
items:
 - kind: Kind
   metadata:
    ...
   spec:
    ...

Content-Types ¶

The API server expects requests to be made as JSON or YAML and responds as JSON or YAML, respectively. Please use the following media types for request content types (Content-Type header) and accepted responses (Accept header).

JSON: application/json
YAML: application/yaml

By default, the API will return JSON.

Resource Versions ¶

The metadata.resourceVersion attribute of a Deployment resources specifies the current logical version of the resource. You can use this field to check whether a resource has been updated since your last request.

Note

Users must not make any assumptions about how resource versions are updated on resource modifications. If you specify a resource version on a modification, this is currently ignored by the API server. There is currently no way to use this field for concurrency control.

API Versioning ¶

Each resource includes an apiVersion attribute that specifies the version of the object.

Any structural changes (such as renaming or removing a field) to a resource require a major version upgrade. Therefore, you can assume that your API resources will not break as long as the version is not upgraded.

Minor changes to the API such as adding optional fields or deprecating fields may happen without a version upgrade. Such changes are treated as non-breaking by the API server and therefore don’t require any intervention on your side.

Responses ¶

Validation Errors ¶

Validation errors are wrapped in ApiValidationException resources.

kind: ApiValidationException
apiVersion: v1
message: <message>
statusCode: <statusCode>
errors:
  - attribute: <attribute>
    message: <message>

The errors array contains each validation error.

API Errors ¶

Generic API errors such as a not found resource or a bad request are wrapped in ApiException resources.

kind: ApiException
apiVersion: v1
message: <message>
reason: <reason>
statusCode: <statusCode>
context:
  key1: value1

Reason is a short String describing the cause of the error. The context map provides optional context to the error.

Status Codes ¶

200: Successful GET request (get single resource or list).
201: Successful POST request (resource created)
400: Bad request (typically due to an ApiValidationException)
401: Unauthorized (request needs authentication)
403: Forbidden (request is not authorized)
404: Resource not found (wrapped in ApiException)
409: Conflict due to resource-specific constraints (wrapped in ApiException)
500: Internal error (wrapped in ApiException)
501: Not implemented due to configuration (wrapped in ApiException)