celerity/api
v2024-07-22 (draft)
blueprint transform: celerity-2024-07-22
The celerity/api
resource type is used to define a HTTP API or a WebSocket API.
An API can be deployed to different target environments such as a Serverless API Gateway1, a containerised environment, or a custom server.
Containerised environments and custom servers use the Celerity runtime for the language of choice to be deployed to handle incoming requests and route them to your application handlers. The Celerity build engine and platforms built on top of it will take care of this for the supported target environments (e.g. Amazon ECS).
Specification
The specification is the structure of the resource definition that comes under the spec
field of the resource in a blueprint.
The rest of this section lists fields that are available to configure the celerity/api
resource followed by examples of different configurations for the resource and how the API behaves in target environments along with additional documentation.
protocols (required)
A list of protocols that the API supports. A Celerity API can support HTTP or WebSocket protocols. Multiple protocols for the same API are supported in certain cases. An API can be both a HTTP and WebSocket API. In a Serverless environment this will map to multiple API Gateways in most cases, in a custom server or containerised environment this will map to a hybrid server that handles both protocols.
The "websocket" protocol is not supported in Serverless environments for Google Cloud and Azure. "Serverless environments" in this context refers to environments where handlers are deployed as serverless functions (e.g. AWS Lambda).
type
array[( "http" | "websocket" | websocketNamedConfiguration )]
cors
Cross-Origin Resource Sharing (CORS) configuration for the API.
type
string | corsConfiguration
examples
cors: "*"
cors:
allowCredentials: true
allowOrigins:
- "https://example.com"
- "https://another.example.com"
allowMethods:
- "GET"
- "POST"
allowHeaders:
- "Content-Type"
- "Authorization"
exposeHeaders:
- "Content-Length"
maxAge: 3600
domain
Configure a custom domain for the API.
type
examples
domain:
domainName: "api.example.com"
basePaths:
- "/"
normalizeBasePath: false
certificateId: "${variables.certificateId}"
securityPolicy: "TLS_1_2"
tracingEnabled
Determines whether tracing is enabled for the API. Depending on the target environment this could mean enabling AWS X-Ray, Google Cloud Trace, or Azure Application Insights.
type
boolean
auth
Configure authorization to control access to the API.
type
examples
auth:
defaultGuard: "jwt"
guards:
jwt:
type: jwt
issuer: "https://identity.twohundred.cloud/oauth2/v1/"
tokenSource: "$.headers.Authorization"
audience:
- "https://identity.twohundred.cloud/api/manage/v1/"
Annotations
Annotations define additional metadata that can determine the behaviour of the resource in relation to other resources in the blueprint or to add behaviour to a resource that is not in its spec.
celerity/vpc
🔗 celerity/api
The following are a set of annotations that determine the behaviour of the API in relation to a VPC. Appropriate security groups are managed by the VPC to API link.
When a VPC is not defined for the container-backed AWS, Google Cloud and Azure target environments, the default VPC for the account will be used.
VPC annotations and links do not have any effect for serverless environments. Serverless APIs are managed by the cloud provider and are not deployed to a customer-managed VPC.
When a VPC is not defined for container-backed cloud environments, annotations in the celerity/api
will apply to the default VPC for the account.
celerity.api.vpc.subnetType
The kind of subnet that the API should be deployed to.
type
string
allowed values
public
| private
default value
public
- When a VPC links to an API, the API will be deployed to a public subnet.
celerity.api.vpc.lbSubnetType
The kind of subnet that the load balancer for an API should be deployed to. This is only relevant when the API is deployed to an environment that requires load balancers to run the API.
type
string
allowed values
public
| private
default value
public
- When a VPC links to an API, the load balancer for the API will be deployed to a public subnet.
Outputs
id
The ID of the created API in the target environment.
For customer server or containerised environments, this will be the same as the baseUrl
output field.
type
string
examples
arn:aws:apigateway:us-east-1::/apis/1234567890
(AWS Serverless)
projects/123456789/locations/global/apis/api-abc
(Google Cloud Serverless)
https://api.example.com/v1
(Custom Server or Containerised Environment)
baseUrl
The base URL of the deployed API.
type
string
examples
https://api.example.com/v1
https://abcdef.execute-api.us-east-1.amazonaws.com
(AWS Serverless)
https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
(Google Cloud Serverless)
Data Types
websocketNamedConfiguration
A named entry for WebSocket configuration.
FIELDS
websocketConfig
Configuration for a WebSocket API.
field type
websocketConfiguration
Configuration for the WebSocket protocol of an API.
FIELDS
routeKey
The key in the message JSON object to use for routing messages to the correct handler. This is not used for binary messages, only for text WebSocket messages. For binary messages, the route is extracted from the prefix of the message as per the Celerity Binary Message Format.
field type
string
default value
event
authStrategy
Determines the strategy for authenticating WebSocket connections.
When authMessage
is set, the client is expected to send a message with an authentication token to authenticate the connection.
When connect
is set, the client is expected to send the authentication token in the connection request headers.
See the WebSocket Auth Strategy section for more information.
In Serverless environments that support WebSocket APIs, only the authMessage
strategy is supported.
This is because custom WebSocket status codes are not supported by Serverless WebSocket API offerings.
field type
string
allowed values
authMessage
| connect
default value
authMessage
corsConfiguration
Detailed Cross-Origin Resource Sharing (CORS) configuration for the API.
FIELDS
allowCredentials
Indicates whether the request is allowed to contain credentials that are set in cookies.
field type
boolean
allowOrigins
A list of origins that are allowed to access the endpoints of the API.
field type
array[string]
allowMethods
A list of HTTP methods that are allowed to be used when accessing the endpoints of the API from an allowed origin.
field type
array[string]
allowHeaders
A list of HTTP headers that are allowed to be used when accessing the endpoints of the API from an allowed origin.
field type
array[string]
exposeHeaders
A list of HTTP headers that can be exposed in responses of the API endpoints for a request from an allowed origin.
field type
array[string]
maxAge
A value that contains the number of seconds to cache a CORS Preflight request for.
field type
string
domainConfiguration
Configuration for attaching a custom domain to the API.
FIELDS
domainName (required)
The custom domain name to use for the API.
field type
string
examples
api.example.com
basePaths
A list of base paths to configure for the API. This is useful when you want to configure the same domain for multiple APIs and route requests to different APIs based on the base path.
When providing protocol-specific base paths, only one can be provided for each protocol; additionally, protocol-specific base paths can not be mixed with simple base paths.
Hybrid APIs that support both HTTP and WebSocket protocols must have protocol-specific base paths defined.
When deploying a Celerity application to a custom server or containerised environment, the base path is used by a reverse proxy or load balancer to route a request to the correct upstream service for a domain that hosts multiple APIs or applications. In a simple set up, the base path should be stripped from the request URL before it reaches the runtime router.
Simple examples where base path should be stripped:
["/"]
["/api/current", "/api/v1"]
When multiple base paths are provided for different protocols, the reverse proxy or load balancer must not strip the base path from the request URL. The presence of the base path in the request allows the runtime router to determine whether to route the request to a HTTP or WebSocket handler.
Advanced example where base path should not be stripped:
- protocol: "http"
basePath: "/api"
- protocol: "websocket"
basePath: "/ws"
field type
array[( string | basePathConfiguration )]
default value
["/"]
examples
- protocol: "http"
basePath: "/api"
- protocol: "websocket"
basePath: "/ws"
normalizeBasePath
A boolean value that indicates whether the base path should be normalised.
When set to true
, the base path will be normalised to remove non-alphanumeric characters.
field type
boolean
default value
true
certificateId (required)
The ID of the certificate to use for the custom domain. This is specific to the target environment where the API is deployed. For example, in AWS, this would be the ARN of an ACM certificate. Usually, it would be best to provide this as a variable to decouple the blueprint from a specific target environment like a cloud provider.
field type
string
examples
arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
"${variables.certificateId}"
securityPolicy
The Transport Layer Security (TLS) version and cipher suite for this domain.
Supported values are TLS_1_0
and TLS_1_2
.
field type
string
allowed values
TLS_1_0
| TLS_1_2
authConfiguration
Configuration for authorization to control access to the API.
FIELDS
guards
A list of guards that are used to control access to the API.
field type
mapping[string, authGuardConfiguration]
defaultGuard
The identifier of the guard that should be used as the default guard for the API. This should only be set when you want to use the same guard for all endpoints of the API.
field type
string
authGuardConfiguration
Configuration for a guard that is used to control access to the API.