REST API & CI/CD¶
In this page we cover the general structure of the Deployment-related API resources. The API endpoints for these resources start with the
You can find more information on accessing Ververica Platform in the installation section.
We ship a Swagger web client that covers all of the Ververica Platform APIs.
- Swagger web client:
The API is split into two parts with separate OpenAPI specifications:
- Ververica Platform:
- Application Manager:
You can select which spec you want to operate against in the upper right corner of the Swagger web client.
All Deployment-related resources are scoped to a Namespace. Each resource is identified by a unique ID. If a resource is not addressable by name, it has to be addressed by its ID.
The following tables show which resources are available and how they are addressed for each of the APIs:
Any resource that can be addressed by name requires their name to be non-empty, unique within a Namespace and immutable. Furthermore, the following naming schemes apply:
- The maximum length of the name is 250 characters.
- Alphanumeric characters (lower- and upper-case), hyphens, and underscores are allowed (
- Any other resource
- The maximum length of the name is 63 characters.
- Only lower-case alphanumeric characters and hyphens are allowed to be used (
- The name is not allowed to start or end with a hyphen.
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 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: ...
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 (
By default, the API will return JSON.
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.
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.
Each resource includes an
apiVersion attribute that specifies the version of the object.
Any structural changes (such as renaming) 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 do not require any intervention on your side.
The Deployment-related APIs use traditional HTTP verbs for CRUD operations on resources. Currently, there is only support for
PUT requests on certain resources.
List resources or request a single resource.
GET /api/v1/namespaces/<namespaceName>/<resourcePlural> GET /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceId> GET /api/v1/namespaces/<namespaceName>/<resourcePlural>/<resourceName>
Create or replace a resource (AKA upsert).
Currently, the only supported resources for this method are
Selectively modify an existing resource.
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, set it to
Example: Remove entries from
spec: template: spec: flinkConfiguration: foo: null bar: baz
The above request will modify the
flinkConfiguration of a Deployment resource as follows:
- Remove entry with key
- Add entry
Delete a resource.
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).
Validation errors are wrapped in
kind: ApiValidationException apiVersion: v1 message: <message> statusCode: <statusCode> errors: - attribute: <attribute> message: <message>
The errors array contains each validation error.
Generic API errors such as a not found resource or a bad request are wrapped in
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.
200: Successful GET request (get single resource or list).
201: Successful POST request (resource created)
400: Bad request (typically due to an
401: Unauthorized (request needs authentication)
403: Forbidden (request is not authorized)
404: Resource not found (wrapped in
409: Conflict due to resource-specific constraints (wrapped in
500: Internal error (wrapped in
501: Not implemented due to configuration (wrapped in