API Gateway Component

Provisions an HTTP API gateway that routes requests to functions and optionally validates tokens via an authentication component. Multiple api-gateway components can be declared in the same configuration — for example, a public API and a separate internal admin API, each with its own domain and route set.

Configuration Fields

Field	Type	Required	Default	Description
type	string	required	—	Must be "api-gateway"
name	string	required	—	Unique component name.
domain	string	required	—	The full domain name for this API (e.g. api.example.com or api.prod.example.com). The base domain is derived automatically as the last two labels and must already be registered and have a hosted zone configured in your cloud provider. The plugin provisions the DNS record and HTTPS certificate for the full domain.
corsOrigins	array of strings	optional	[]	Allowed CORS origins. When set, CORS uses those specific origins with allowCredentials: true (required for cookie-based auth). When omitted or empty, uses * without credentials (works for JWT auth via the Authorization header). Use specific origins when your frontend needs to send cookies or credentials.
protocol	string	optional	http	API protocol. http (default) provisions an HTTP API with method + path routes. websocket provisions an AWS API Gateway WebSocket API whose routes use a routeKey (see the WebSocket APIs section below). protocolType: "WEBSOCKET" is also accepted.
routeSelectionExpression	string	optional	$request.body.action	WebSocket only. Expression API Gateway evaluates against each incoming message to choose the matching routeKey.
throttlingRateLimit	integer	optional	—	Maximum requests per second. Provider-specific limits apply.
throttlingBurstLimit	integer	optional	—	Maximum concurrent requests (burst). AWS only.
routes	array	optional	—	Explicit route definitions. If omitted, routes are derived from referenced functions.
preProcessFunction	string	optional	—	Name of a function component to invoke before every request is routed. Runs before authentication and routing. Useful for request transformation, header injection, or IP filtering. The function receives the raw request and must return a modified request or an error response to short-circuit the pipeline.
postProcessFunction	string	optional	—	Name of a function component to invoke after every response is produced. Runs after the route function returns. Useful for response transformation, audit logging, or adding security headers. The function receives the response and must return a (possibly modified) response.
references	array of strings	optional	—	Names of components this gateway references that are not already named in a dedicated field. Any component named in routes[].function, routes[].auth, preProcessFunction, or postProcessFunction is treated as an implicit reference and does not need to be listed here. In most cases, use the links array with full link objects instead.

The base domain (last two labels of domain) must already be registered and have a hosted zone configured in your cloud provider — Route 53 (AWS), Azure DNS, or Cloud DNS (GCP). The plugin derives the base domain automatically: api.example.com → base example.com, api.prod.example.com → base example.com. It then provisions the full DNS record and an HTTPS certificate for the exact domain you specify.

Route Object

Field	Type	Required	Description
method	string	required	HTTP method: GET, POST, PUT, DELETE, PATCH, ANY
path	string	required	Route path, e.g. /users/{id}. No duplicate sibling paths allowed.
function	string	required	Name of the function component to invoke.
auth	string	optional	Name of the authentication component to use for token validation on this route.

Any component name that appears in a dedicated field — routes[].function, routes[].auth, preProcessFunction, or postProcessFunction — is treated as an implicit reference. The plugin validates and wires these automatically. Only add a component to links if it is not already named in one of those fields.

Cloud Resources Created

API Gateway HTTP API v2 — low-latency HTTP API with automatic payload format version 2.0. HTTPS only.
API Gateway Stage — $default stage with auto-deploy enabled.
Lambda Integrations — one integration per referenced function. Existing integrations are reused by URI match on redeploy.
Lambda Authorizer / JWT Authorizer — if an authentication component is referenced, a JWT authorizer is created using the Cognito User Pool as the issuer.
Pre-process Lambda Integration — if preProcessFunction is set, a Lambda integration is wired as a request interceptor before routing.
Post-process Lambda Integration — if postProcessFunction is set, a Lambda integration is wired as a response interceptor after the route function returns.
ACM Certificate — provisioned in the deployment region for the configured domain. DNS-validated against the base domain's Route 53 hosted zone.
API Gateway Custom Domain — maps the domain to the API stage.
Route 53 Record — A/ALIAS record for the domain pointing to the API Gateway endpoint.

Declarative Sync: On redeploy, the deployer fetches all existing routes and integrations (with pagination), reuses integrations by URI match, creates or updates routes as needed, and deletes stale routes and orphaned integrations. ConflictException on route creation is handled gracefully by falling back to update.

Retry: All API Gateway SDK calls are retried with exponential backoff (5 retries, 1s base delay) on 429 Too Many Requests or 5xx errors.

JSON Example

{
  "type": "api-gateway",
  "name": "main-api",
  "domain": "api.example.com",
  "throttlingRateLimit": 1000,
  "preProcessFunction": "request-transformer",
  "postProcessFunction": "response-auditor",
  "routes": [
    {
      "method": "ANY",
      "path": "/api/{proxy+}",
      "function": "api-handler",
      "auth": "user-auth"
    },
    {
      "method": "GET",
      "path": "/health",
      "function": "health-check"
    }
  ],
  "references": []
}

All named components are declared via dedicated fields: route functions via function, authentication via auth, and processors via preProcessFunction / postProcessFunction. None of them need to appear in references.

Note: The references field is a legacy shorthand. Prefer using the links array with full link objects (sourceComponent, targetComponent, linkType) for explicit component relationships. All function/auth references in routes are implicit and need neither references nor links.

WebSocket APIs

Set protocol to websocket to provision an AWS API Gateway WebSocket API instead of an HTTP API. This is the serverless fit for real-time features such as group chat: connections are managed by API Gateway and each message is routed to a backing function by route key rather than by HTTP method and path.

{
  "type": "api-gateway",
  "name": "chat-ws",
  "providerSettings": {
    "protocol": "websocket",
    "domain": "ws.example.com",
    "routeSelectionExpression": "$request.body.action",
    "routes": [
      { "routeKey": "$connect",    "function": "chat-connect" },
      { "routeKey": "$disconnect", "function": "chat-disconnect" },
      { "routeKey": "sendMessage", "function": "chat-send" }
    ]
  },
  "links": []
}

Field	Type	Required	Description
routeKey	string	required	Unique per gateway. Reserved keys: $connect (client connects), $disconnect (client disconnects), $default (fallback). Any other value is a custom key selected by routeSelectionExpression (e.g. sendMessage).
function	string	required	Name of the function that handles this route. Must reference an existing function component.

Behaviour:

Route-level authorization is NONE. Authenticate and authorize inside the $connect handler — WebSocket authorization happens at connection time. auth, JWT authorizers, and preProcessFunction are ignored for WebSocket APIs.
Integrations are Lambda proxy (AWS_PROXY) with payload format version 1.0.
The API is deployed to the $default stage with auto-deploy enabled.
CORS is not configured (WebSocket APIs do not support the HTTP CORS object).
Each backing function is automatically granted execute-api:ManageConnections (scoped to arn:aws:execute-api:*:*:*/*/POST/@connections/*) via an implicit FUNCTION_TO_API_GATEWAY link, allowing it to post messages back to connected clients through the @connections API.

Validation: For WebSocket gateways, each route must declare a non-blank, unique routeKey and a function that exists in the configuration. Missing route functions produce a clear validation error.

API Gateway Component

Configuration Fields

Route Object

Cloud Resources Created

JSON Example

WebSocket APIs

Links

← Referenced by

Can reference →

Can reference →