AWS.ApiGateway reference

Account

Source: src/AWS/ApiGateway/Account.ts

Account-level settings for Amazon API Gateway in the current region (CloudWatch logging role, etc.).

Account: Account settings

yield* ApiGateway.Account("Account", {
  cloudwatchRoleArn: role.roleArn,
});

ApiKey

Source: src/AWS/ApiGateway/ApiKey.ts

API Gateway API key for usage plans and apiKeyRequired methods.

ApiKey: API keys

const key = yield* ApiGateway.ApiKey("PartnerKey", {
  generateDistinctId: true,
});

Authorizer

Source: src/AWS/ApiGateway/Authorizer.ts

REST API Lambda, Cognito, or gateway authorizer.

Authorizer: Authorizers

const authorizer = yield* ApiGateway.Authorizer("Auth", {
  restApiId: api.restApiId,
  type: "TOKEN",
  authorizerUri: authorizerInvokeArn,
  identitySource: "method.request.header.Authorization",
});

BasePathMapping

Source: src/AWS/ApiGateway/BasePathMapping.ts

Maps a custom domain name path to a REST API stage.

BasePathMapping: Custom domain

yield* ApiGateway.BasePathMapping("Root", {
  domainName: domain.domainName,
  restApiId: api.restApiId,
  stage: stage.stageName,
});

CreateApiKey

Source: src/AWS/ApiGateway/CreateApiKey.ts

Runtime binding for issuing API Gateway API keys (apigateway:POST on /apikeys). Account-scoped — takes no resource.

The response’s value is Redacted<string> (distilled marks it sensitive), so the plaintext key never leaks into logs. Provide ApiGateway.CreateApiKeyHttp on the Function effect to implement the binding.

CreateApiKey: Issuing API keys

import * as Redacted from "effect/Redacted";

// init — account-level binding takes no resource
const createApiKey = yield* ApiGateway.CreateApiKey();

// runtime
const key = yield* createApiKey({
  name: `customer-${customerId}`,
  enabled: true,
});
const plaintext = Redacted.isRedacted(key.value)
  ? Redacted.value(key.value)
  : key.value;

CreateUsagePlanKey

Source: src/AWS/ApiGateway/CreateUsagePlanKey.ts

Runtime binding for enrolling an API key in a UsagePlan (apigateway:POST on /usageplans/{id}/keys).

The core of a self-service API-key onboarding flow: issue a key with ApiGateway.CreateApiKey, then attach it to the plan that throttles and meters it. Provide ApiGateway.CreateUsagePlanKeyHttp on the Function effect to implement the binding.

CreateUsagePlanKey: Managing plan keys

// init
const createApiKey = yield* ApiGateway.CreateApiKey();
const createUsagePlanKey = yield* ApiGateway.CreateUsagePlanKey(plan);

// runtime
const key = yield* createApiKey({ name: customerId, enabled: true });
yield* createUsagePlanKey({ keyId: key.id! });

DeleteApiKey

Source: src/AWS/ApiGateway/DeleteApiKey.ts

Runtime binding for deleting an API Gateway API key (apigateway:DELETE on /apikeys/{id}). Account-scoped — takes no resource.

Provide ApiGateway.DeleteApiKeyHttp on the Function effect to implement the binding.

DeleteApiKey: Managing API keys

// init
const deleteApiKey = yield* ApiGateway.DeleteApiKey();

// runtime
yield* deleteApiKey({ apiKey: keyId }).pipe(
  Effect.catchTag("NotFoundException", () => Effect.void),
);

DeleteUsagePlanKey

Source: src/AWS/ApiGateway/DeleteUsagePlanKey.ts

Runtime binding for removing an API key from a UsagePlan (apigateway:DELETE on /usageplans/{id}/keys/{keyId}).

Provide ApiGateway.DeleteUsagePlanKeyHttp on the Function effect to implement the binding.

DeleteUsagePlanKey: Managing plan keys

// init
const deleteUsagePlanKey = yield* ApiGateway.DeleteUsagePlanKey(plan);

// runtime
yield* deleteUsagePlanKey({ keyId }).pipe(
  Effect.catchTag("NotFoundException", () => Effect.void),
);

DeploymentResource

Source: src/AWS/ApiGateway/Deployment.ts

A point-in-time snapshot of a REST API, ready to be served through a Stage.

DeploymentResource: Creating a deployment

A Deployment captures whatever methods, integrations, resources, and authorizers currently exist on the REST API and produces an immutable deploymentId that a Stage can point at. Pass the RestApi value on restApi and Alchemy handles all the ordering for you — the deployment will run after every method bound to the API.

const api = yield* ApiGateway.RestApi("Api", {
  endpointConfiguration: { types: ["REGIONAL"] },
});

yield* ApiGateway.Method("GetRoot", {
  restApi: api,
  httpMethod: "GET",
  authorizationType: "NONE",
  integration: { type: "MOCK" },
});

const deployment = yield* ApiGateway.Deployment("Release", {
  restApi: api,
  description: "v1",
});

DeploymentResource: Forcing a redeploy

Usually you do not have to: restApi already makes the Deployment depend on every method, so any change to a method re-plans a new deployment. Use triggers when you want to couple the deployment to a signal Alchemy cannot see — for example, a manual version bump or a hash of configuration computed outside the stack.

const deployment = yield* ApiGateway.Deployment("Release", {
  restApi: api,
  triggers: { version: "2026-05-01" },
});

DeploymentResource: Why no DependsOn?

CloudFormation’s AWS::ApiGateway::Deployment famously requires a hand-written DependsOn: [Method1, Method2, ...] listing every method. Alchemy derives that list automatically from the bindings registered on the RestApi, so adding a method never requires editing the deployment.

DomainName

Source: src/AWS/ApiGateway/DomainName.ts

Custom domain name for an Amazon API Gateway REST API.

DomainName: Custom domain

const domain = yield* ApiGateway.DomainName("ApiDomain", {
  domainName: "api.example.com",
  regionalCertificateArn: cert.certificateArn,
  endpointConfiguration: { types: ["REGIONAL"] },
  securityPolicy: "TLS_1_2",
});

FlushStageAuthorizersCache

Source: src/AWS/ApiGateway/FlushStageAuthorizersCache.ts

Runtime binding for flushing a stage’s authorizer result cache (apigateway:DELETE on /restapis/{id}/stages/{name}/cache/authorizers).

Bind a Stage inside a function runtime to drop cached authorizer verdicts — e.g. immediately revoking access after a permission change, without waiting out authorizerResultTtl. Provide ApiGateway.FlushStageAuthorizersCacheHttp on the Function effect to implement the binding.

FlushStageAuthorizersCache: Flushing caches

// init
const flushAuthorizers = yield* ApiGateway.FlushStageAuthorizersCache(stage);

// runtime
yield* flushAuthorizers();

FlushStageCache

Source: src/AWS/ApiGateway/FlushStageCache.ts

Runtime binding for flushing a stage’s response cache (apigateway:DELETE on /restapis/{id}/stages/{name}/cache/data).

Bind a Stage inside a function runtime to invalidate cached responses after a content update. Provide ApiGateway.FlushStageCacheHttp on the Function effect to implement the binding.

FlushStageCache: Flushing caches

// init
const flushStageCache = yield* ApiGateway.FlushStageCache(stage);

// runtime
yield* flushStageCache();

GatewayResource

Source: src/AWS/ApiGateway/GatewayResource.ts

A path segment under a REST API resource tree.

Resources form the URL hierarchy of a REST API: every path segment (/items, /items/{id}, /{proxy+}) is a Resource whose parentId points either at api.rootResourceId (for top-level paths) or at another Resource’s resourceId (for nested paths). Attach methods to a resource by passing its resourceId to ApiGateway.Method.

GatewayResource: Path resources

Top-level path

const items = yield* ApiGateway.Resource("Items", {
  restApi: api,
  parentId: api.rootResourceId,
  pathPart: "items",
});

Nested path with a greedy proxy

const items = yield* ApiGateway.Resource("Items", {
  restApi: api,
  parentId: api.rootResourceId,
  pathPart: "items",
});

const anyItem = yield* ApiGateway.Resource("AnyItem", {
  restApi: api,
  parentId: items.resourceId,
  pathPart: "{proxy+}",
});

GatewayResponse

Source: src/AWS/ApiGateway/GatewayResponse.ts

Gateway response mapping for a REST API (e.g. DEFAULT_4XX, DEFAULT_5XX).

GatewayResponse: Gateway responses

yield* ApiGateway.GatewayResponse("Default4xx", {
  restApiId: api.restApiId,
  responseType: "DEFAULT_4XX",
  responseTemplates: { "application/json": '{"message":$context.error.messageString}' },
});

GetApiKey

Source: src/AWS/ApiGateway/GetApiKey.ts

Runtime binding for reading a single API Gateway API key (apigateway:GET on /apikeys/{id}). Account-scoped — takes no resource.

With includeValue: true the response’s value is Redacted<string>. Provide ApiGateway.GetApiKeyHttp on the Function effect to implement the binding.

GetApiKey: Managing API keys

// init
const getApiKey = yield* ApiGateway.GetApiKey();

// runtime
const key = yield* getApiKey({ apiKey: keyId });

GetApiKeys

Source: src/AWS/ApiGateway/GetApiKeys.ts

Runtime binding for listing API Gateway API keys (apigateway:GET on /apikeys). Account-scoped — takes no resource.

Provide ApiGateway.GetApiKeysHttp on the Function effect to implement the binding.

GetApiKeys: Managing API keys

// init
const getApiKeys = yield* ApiGateway.GetApiKeys();

// runtime
const page = yield* getApiKeys({ nameQuery: "customer-", limit: 100 });

GetUsage

Source: src/AWS/ApiGateway/GetUsage.ts

Runtime binding for reading usage data of a UsagePlan (apigateway:GET on /usageplans/{id}/usage).

Bind a usage plan inside a function runtime to meter per-key API consumption — the primitive for building billing or quota dashboards. Provide ApiGateway.GetUsageHttp on the Function effect to implement the binding.

GetUsage: Metering usage

// init
const getUsage = yield* ApiGateway.GetUsage(plan);

// runtime
const usage = yield* getUsage({
  keyId,
  startDate: "2026-07-01",
  endDate: "2026-07-14",
});

GetUsagePlanKey

Source: src/AWS/ApiGateway/GetUsagePlanKey.ts

Runtime binding for reading a single API key enrolled in a UsagePlan (apigateway:GET on /usageplans/{id}/keys/{keyId}).

Provide ApiGateway.GetUsagePlanKeyHttp on the Function effect to implement the binding.

GetUsagePlanKey: Managing plan keys

// init
const getUsagePlanKey = yield* ApiGateway.GetUsagePlanKey(plan);

// runtime
const enrolled = yield* getUsagePlanKey({ keyId }).pipe(
  Effect.map(() => true),
  Effect.catchTag("NotFoundException", () => Effect.succeed(false)),
);

GetUsagePlanKeys

Source: src/AWS/ApiGateway/GetUsagePlanKeys.ts

Runtime binding for listing the API keys enrolled in a UsagePlan (apigateway:GET on /usageplans/{id}/keys).

Provide ApiGateway.GetUsagePlanKeysHttp on the Function effect to implement the binding.

GetUsagePlanKeys: Managing plan keys

// init
const getUsagePlanKeys = yield* ApiGateway.GetUsagePlanKeys(plan);

// runtime
const page = yield* getUsagePlanKeys({ limit: 100 });

MethodResource

Source: src/AWS/ApiGateway/Method.ts

An HTTP method on an API Gateway Resource.

A Method is a single HTTP verb (GET, POST, ANY, …) attached to a REST API resource path. Most methods also carry an integration — the downstream target that actually handles the request (a Lambda function, an HTTP endpoint, a mock response, etc.).

MethodResource: Binding to a RestApi

Pass the RestApi value on restApi. This threads the API id through and registers the method as a RestApiBinding on the API, so that any Deployment of the same API is automatically ordered after this method completes. You do not need to manage Deployment.triggers yourself.

yield* ApiGateway.Method("GetRoot", {
  restApi: api,
  httpMethod: "GET",
  authorizationType: "NONE",
  integration: { type: "MOCK" },
});

MethodResource: Lambda proxy integration

For Lambda-backed APIs, the integration uri follows the arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<function-arn>/invocations shape. Use Output.map to resolve the function ARN before building the URI, since the function’s ARN is only known at deploy time.

import * as Output from "alchemy/Output";

const invokeUri = Output.map(
  fn.functionArn,
  (arn) =>
    `arn:aws:apigateway:${region}:lambda:path/2015-03-31/functions/${arn}/invocations`,
);

yield* ApiGateway.Method("RootAny", {
  restApi: api,
  httpMethod: "ANY",
  authorizationType: "NONE",
  integration: {
    type: "AWS_PROXY",
    integrationHttpMethod: "POST",
    uri: invokeUri,
  },
});

MethodResource: Methods on sub-paths

Attach a method to a nested path by creating an ApiGateway.Resource and passing its resourceId explicitly. restApi is still required so the method binds for deployment ordering.

const items = yield* ApiGateway.Resource("Items", {
  restApi: api,
  parentId: api.rootResourceId,
  pathPart: "items",
});

yield* ApiGateway.Method("ListItems", {
  restApi: api,
  resourceId: items.resourceId,
  httpMethod: "GET",
  authorizationType: "NONE",
  integration: { type: "MOCK" },
});

RestApi

Source: src/AWS/ApiGateway/RestApi.ts

An Amazon API Gateway REST API (v1).

RestApi is the root of an API Gateway v1 stack. Every other ApiGateway resource — Resource, Method, Authorizer, Deployment, Stage — hangs off a RestApi. The only identity you need to thread through your stack is the RestApi value itself: child resources accept restApi: api and register themselves back onto the API so that deployments and stages wait for them without any user-authored dependency lists.

RestApi: Getting started

A minimal API Gateway stack is four pieces: the RestApi, one or more Methods, a Deployment that snapshots those methods, and a Stage that exposes the deployment at a URL.

import * as ApiGateway from "alchemy/AWS/ApiGateway";

const api = yield* ApiGateway.RestApi("Api", {
  endpointConfiguration: { types: ["REGIONAL"] },
});

yield* ApiGateway.Method("GetRoot", {
  restApi: api,
  httpMethod: "GET",
  authorizationType: "NONE",
  integration: { type: "MOCK" },
});

const deployment = yield* ApiGateway.Deployment("Release", {
  restApi: api,
});

const stage = yield* ApiGateway.Stage("Prod", {
  restApi: api,
  stageName: "prod",
  deploymentId: deployment.deploymentId,
});

RestApi: How dependencies flow

Writing restApi: api on a child (rather than restApiId: api.restApiId) does two things: it threads the restApi id through, and it registers a RestApiBinding back onto the API. The Alchemy scheduler sees those bindings as reverse edges from children into the API, and Deployment reads them to express a transitive dependency on every child. You never have to write a DependsOn list or a triggers hash — adding a new Method automatically orders it before the next Deployment.

RestApi: Private REST APIs

const api = yield* ApiGateway.RestApi("PrivateApi", {
  endpointConfiguration: {
    types: ["PRIVATE"],
    vpcEndpointIds: [endpoint.vpcEndpointId],
  },
  policy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: "*",
      Action: "execute-api:Invoke",
      Resource: "*",
    }],
  }),
});

RestApi: Binary payloads

const api = yield* ApiGateway.RestApi("BinaryApi", {
  binaryMediaTypes: ["application/octet-stream", "image/png"],
  minimumCompressionSize: 1024,
});

RestApi: Endpoint hardening

const api = yield* ApiGateway.RestApi("CustomDomainOnlyApi", {
  endpointConfiguration: { types: ["REGIONAL"] },
  disableExecuteApiEndpoint: true,
});

RestApiEventSource

Source: src/AWS/ApiGateway/RestApiEventSource.ts

Event source connecting a RestApi route to the hosting Lambda function.

At deploy time the Lambda implementation (Lambda.RestApiEventSource) materializes the path Resources, the Method with an AWS_PROXY integration, and the invoke Permission for the route — and registers each of them as bindings on the API so any Deployment of the same API is ordered after them. At runtime it dispatches matching REST proxy events to the handler. Subscribe routes with onRestApiRoute and provide Lambda.RestApiEventSource on the hosting function.

RestApiEventSource: Handling REST API routes

export default MyFunction.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    const api = yield* ApiGateway.RestApi("Api", {
      endpointConfiguration: { types: ["REGIONAL"] },
    });

    yield* ApiGateway.onRestApiRoute(
      api,
      { path: "/items", httpMethod: "GET" },
      (event) =>
        Effect.succeed({
          statusCode: 200,
          body: JSON.stringify({ items: [] }),
        }),
    );

    const deployment = yield* ApiGateway.Deployment("Release", {
      restApi: api,
    });
    yield* ApiGateway.Stage("Prod", {
      restApi: api,
      stageName: "prod",
      deploymentId: deployment.deploymentId,
    });

    return {};
  }).pipe(Effect.provide(Lambda.RestApiEventSource)),
);

StageResource

Source: src/AWS/ApiGateway/Stage.ts

A stage for a REST API deployment.

A Stage is what clients actually call. It binds a name (dev, prod, v2) to a specific Deployment of a RestApi and exposes it at a stable URL:

https://<restApiId>.execute-api.<region>.amazonaws.com/<stageName>/

StageResource: Stages

const stage = yield* ApiGateway.Stage("Dev", {
  restApi: api,
  stageName: "dev",
  deploymentId: deployment.deploymentId,
});

StageResource: Stage variables

const stage = yield* ApiGateway.Stage("Prod", {
  restApi: api,
  stageName: "prod",
  deploymentId: deployment.deploymentId,
  variables: {
    logLevel: "info",
    featureFlag: "on",
  },
});

StageResource: Canary deployments

Point canarySettings at a different Deployment to split traffic between the stable and canary versions. percentTraffic is the percent of requests routed to the canary deployment.

const stage = yield* ApiGateway.Stage("Prod", {
  restApi: api,
  stageName: "prod",
  deploymentId: stableDeployment.deploymentId,
  canarySettings: {
    percentTraffic: 10,
    deploymentId: canaryDeployment.deploymentId,
  },
});

UpdateApiKey

Source: src/AWS/ApiGateway/UpdateApiKey.ts

Runtime binding for patching an API Gateway API key (apigateway:PATCH on /apikeys/{id}). Account-scoped — takes no resource.

Provide ApiGateway.UpdateApiKeyHttp on the Function effect to implement the binding.

UpdateApiKey: Managing API keys

// init
const updateApiKey = yield* ApiGateway.UpdateApiKey();

// runtime
yield* updateApiKey({
  apiKey: keyId,
  patchOperations: [{ op: "replace", path: "/enabled", value: "false" }],
});

UpdateUsage

Source: src/AWS/ApiGateway/UpdateUsage.ts

Runtime binding for granting a temporary quota extension to an API key on a UsagePlan (apigateway:PATCH on /usageplans/{id}/keys/{keyId}/usage).

Provide ApiGateway.UpdateUsageHttp on the Function effect to implement the binding.

UpdateUsage: Metering usage

// init
const updateUsage = yield* ApiGateway.UpdateUsage(plan);

// runtime
yield* updateUsage({
  keyId,
  patchOperations: [
    { op: "replace", path: "/remaining", value: "500" },
  ],
});

UsagePlan

Source: src/AWS/ApiGateway/UsagePlan.ts

Usage plan for API stages, throttling, and quotas.

UsagePlan: Usage plans

Usage plan with stage

const plan = yield* ApiGateway.UsagePlan("Standard", {
  apiStages: [{ apiId: api.restApiId, stage: stage.stageName }],
});

Throttled plan with a quota and an enrolled API key

const plan = yield* ApiGateway.UsagePlan("Partner", {
  throttle: { rateLimit: 10, burstLimit: 20 },
  quota: { limit: 10_000, period: "MONTH" },
});

const key = yield* ApiGateway.ApiKey("PartnerKey", {
  generateDistinctId: true,
});

yield* ApiGateway.UsagePlanKey("PartnerLink", {
  usagePlanId: plan.id,
  keyId: key.id,
});

UsagePlanKey

Source: src/AWS/ApiGateway/UsagePlanKey.ts

Associates an API key with a usage plan.

UsagePlanKey: Usage plan keys

yield* ApiGateway.UsagePlanKey("PlanKey", {
  usagePlanId: plan.id,
  keyId: key.id,
});

VpcLink

Source: src/AWS/ApiGateway/VpcLink.ts

VPC link for private integrations (connectionType: "VPC_LINK" on a method integration).

VpcLink: Private integrations

const link = yield* ApiGateway.VpcLink("NlbLink", {
  description: "Link to internal NLB",
  targetArns: [nlb.loadBalancerArn],
});

yield* ApiGateway.Method("PrivateGet", {
  restApiId: api.restApiId,
  resourceId: resource.resourceId,
  httpMethod: "GET",
  integration: {
    type: "HTTP_PROXY",
    integrationHttpMethod: "GET",
    uri: "https://api.internal.example.com/hello",
    connectionType: "VPC_LINK",
    connectionId: link.vpcLinkId,
  },
});