Skip to main content
Version: 1.0

Deploy Engine API

v1 of the Deploy Engine HTTP API provides a set of endpoints for interacting with the Deploy Engine to validate and deploy blueprints used for Celerity applications and infrastructure-as-code. The API contains a mixture of resource-oriented RESTful endpoints, action-oriented RPC-style endpoints and event streaming endpoints.

The API is designed in a way that a RESTful resource operation call is made to start a process such as validating a blueprint document or deploying a blueprint instance, where the state of the resource representing a process can be retrieved using a unique identifier. This resource ID can also be used to stream events as the underlying validation, change staging or deployment process is running.

This API is intended to be used by trusted clients that represent server-side applications or applications running on the same host as the Deploy Engine (such as the Celerity CLI). To provide a service to end users, such as a Platform-as-a-Service offering, the Deploy Engine should be used as the core engine where the platform provides its own API layer to manage authorisation, multi-tenancy, versioning and long-term history.

Connecting​

Version 1 of the Deploy Engine HTTP API can be connected to over TCP/IP using HTTP or HTTPS or over a Unix domain socket. Unix domain sockets are useful for instances of the Deploy Engine that are running on the same host as the client making the request, such as the default installation of Celerity where the Deploy Engine is running as a local process that the CLI communicates with.

Base URL:

http(s)://{host}(:{port})(/{basePath})/v1

A base URL in this format is used to access the Deploy Engine API over a network. For a unix domain socket, the only relevant part of the base URL is the version path prefix /v1, the scheme, host and port can be any value when making requests over a HTTP client that supports Unix domain sockets.

{host} is the host name or IP address of the server running the Deploy Engine.

{port} is the port number that the Deploy Engine is listening on. In most cases, this will be omitted as public instances of the Deploy Engine will be accessible over the default HTTPS port (443).

{basePath} is the base path for the API, some deployments may provide a dedicated base path for the Deploy Engine API.

In production environments, where the Deploy Engine is accessible over the public internet, the server running the Deploy Engine must use the https scheme to ensure that all data is encrypted in transit. This means that base URLs for Deploy Engine instances running in production should look something like this:

https://api.deploy.celerityframework.io/v1

Event Streams​

Validation, change staging and deployment processes are all asynchronous and can take a long time to complete, so the API provides stream endpoints that use Server-Sent Events (SSE) to stream events from the Deploy Engine to the client as they occur. This allows clients to receive real-time updates on the progress of long-running processes. For stream endpoints, clients can send a Last-Event-ID header to the server to resume the stream from a specific event ID, allowing clients to reconnect to the stream and receive events that they may have missed while disconnected. The endpoints to retrieve validation results, change sets and deployment instances are also provided to allow the client to retrieve the full picture of the current state of each of these resource types.

When making a request to one of the */events stream endpoints, the Deploy Engine will queue events server-side if the client is not yet connected to the stream. This allows the client to receive events that have occurred in the time between the process starting and the client connecting to the stream. These events will be queued server-side and will be cleaned up after an amount of time that will be configured for the Deploy Engine instance.

v1 of the Deploy Engine is not designed to be relied upon to retain long-term event history, clients are responsible for storing events that they receive from the stream endpoints if required. In order for this to be as reliable as possible, clients should properly implement usage of the Last-Event-ID header to resume the stream from a specific event ID to capture any missed events when reconnecting to the stream.

If a request to a stream endpoint is made after the process has completed, events that have been retained server-side will be sent to the client in the order that they occurred. As events are cleaned up periodically depending on how the Deploy Engine is configured, as mentioned above, clients should not rely on the stream endpoints to provide a complete history of events for a process.

Short-lived Resources​

Validation results and change sets are short-lived resources that are expected to be cleaned up after an amount of time that is configured for the Deploy Engine instance. This means that clients should not rely on these resources to be available indefinitely, these resources should be used shortly after the time of the action that created them. Clients can build their own layers on top of the Deploy Engine API to store these resources for longer periods of time if required. This could be useful for Platform-as-a-service offerings that want to provide a history of validation results or change sets for their users to view in their own UI with a longer retention period.

Authenticating with the Deploy Engine​

The Deploy Engine HTTP API supports authentication using API keys, JWTs and the Celerity Signature v1. The authentication mechanism to use when making requests will depend on how the Deploy Engine is configured.

v1 of the Deploy Engine will attempt to authenticate requests using the following order of precedence:

  1. JWT: If the Authorization header is present, using the bearer scheme and contains a valid JWT, the JWT will be verified and used to authenticate the request. This will be skipped if an adequate OIDC/OAuth2 provider is not configured as the token issuer for the Deploy Engine instance.
  2. Celerity Signature v1: If the Celerity-Signature-V1 header is present, using the Celerity Signature v1 format, the signature will be verified and used to authenticate the request. This will be skipped if the Deploy Engine instance is not configured with at least one key pair for the Celerity Signature v1 authentication mechanism.
  3. API Key: If the Celerity-Api-Key header is present, using the API key scheme and contains a valid API key, the API key will be used to authenticate the request. This will be skipped if the Deploy Engine instance is not configured with at least one API key for the API key authentication mechanism.

See the Authentication documentation to read more about the authentication mechanisms supported by Celerity components including but not limited to the Deploy Engine.

Authentication​

OAuth2/OIDC auth using JWT Bearer tokens. The token issuer will be configured independently for each Deploy Engine instance.

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Token URL: [issuerTokenEndpoint]

Scopes:

    License

    Apache 2.0