Ververica Platform: Self-Managed REST API (v2.x)

This page covers the general structure of the deployment-related API resources for Ververica Platform: Self-Managed version 2.x. The API endpoints for these resources start with the /api prefix.

note

If you are looking for the Ververica REST API Reference for the Ververica Cloud: Managed Service or Ververica Cloud: Bring Your Own Cloud deployment options, go to Ververica OpenAPI Reference

Swagger

Swagger ships a web client that covers all of the Ververica Platform APIs.

• Swagger web client: /swagger

The API is split into two parts with separate specifications:

• **Ververica Platform: Self-Managed **: /swagger.json
• Application Manager: /api/swagger.json

You can select which specification you want to operate against in the upper right corner of the Swagger web client.

Resource Objects

Deployment-related resources are always scoped to a Namespace and uniquely identified by an ID. If a resource does not support name-based addressing, it must be accessed via its ID.

APIs

The following tables show which resources are available and how they are addressed for each of the APIs:

AppManager API 2.x

Resource	Name-Addressable
Deployment	✓
DeploymentDefaults	✗
DeploymentTarget	✓
Event	✗
Job	✗
Savepoint	✗
SecretValue	✓
SessionCluster	✓

Ververica Platform: Self-Managed API 2.x

Resource	Name-Addressable
ApiTokens	✓
Catalogs	✓
CatalogConnectors	✓
Connectors	✓
Formats	✓
SqlScripts	✓
UdfArtifacts	✓

Names

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:

• DeploymentTarget & SecretValue

  • The maximum length of the name is 250 characters.

  • Alphanumeric characters (lower- and upper-case), hyphens, and underscores are allowed ([0-9a-zA-Z-_]).

  • Examples:

    • Resource_Name_01
    • resource-name-01

• Any other resource

  • The maximum length of the name is 63 characters.

  • Only lower-case alphanumeric characters and hyphens are allowed to be used ([-0-9a-z]).

  • The name is not allowed to start or end with a hyphen.

  • Examples:

    • resource-name-01

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) 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.

Verbs

The Deployment-related APIs use traditional HTTP verbs for CRUD operations on resources. Currently, there is only support for PUT requests on certain resources. Ververica Platform: Self-Managed v2.x uses traditional HTTP verbs for CRUD operations on resources. They define the type of operation a client performs on a resource. Understanding how each verb is used helps ensure correct, predictable interactions with the API. The following section explains what each verb does and when to use it within the Ververica Platform: Self-Managed

GET

Retrieve data without modifying it. You can 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>

POST

Create a new resource.

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

PUT

Fully create or replace a resource (AKA upsert).

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

note

Currently, the only supported resources for the PUT request method are: Deployment, DeploymentTarget, and SessionCluster.

PATCH

Selectively modify or update 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 null.

Example: Remove entries from flinkConfiguration

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 foo.
• Add entry bar: baz.

DELETE

Remove a resource.

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

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

note

You can only delete user-managed resources. Some resources must be in a specific state before deletion is allowed. For example, a Deployment must be stopped (not in the RUNNING state) before you can remove it.

Responses

Validation Errors

Validation errors are wrapped in ApiValidationException resources. The errors array includes one entry for each validation error encountered during request processing.

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. You can enter a reason (a short string) that describes the cause of the error. You can also use the context map to provide optional context for the error.

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

Status Codes

Status codes provide a standardized way for APIs to communicate the outcome of a request. They help clients understand what went wrong, enable appropriate automated responses, and support easier debugging. The following list outlines common status codes used in the Ververica Platform: Self-Managed v2.x responses.

• 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)