API Gateway

AWS Service Integrations

API Gateway integrates directly with AWS services without Lambda. Two implementation approaches:

• REST API and WebSocket API: Use Type: AWS with VTL mapping templates for full request/response transformation. Supports any AWS service action. Both synchronous (wait for response) and asynchronous (fire-and-forget) patterns

• HTTP API: Uses first-class integrations (Type: AWS_PROXY with IntegrationSubtype) and parameter mapping instead of VTL. Supported subtypes: EventBridge-PutEvents, SQS-SendMessage, SQS-ReceiveMessage, SQS-DeleteMessage, SQS-PurgeQueue, Kinesis-PutRecord, StepFunctions-StartExecution, StepFunctions-StartSyncExecution, StepFunctions-StopExecution, AppConfig-GetConfiguration. For services not in this list (DynamoDB, SNS, S3), use Lambda proxy instead. See Integration subtype reference

The patterns below cover the most commonly used service integrations. REST API Type: AWS can integrate with any AWS service that exposes an HTTP API; the same approach (URI, IAM role, VTL mapping) applies to services not listed here. For HTTP API first-class integrations, the same services apply but use parameter mapping ($request.body, $request.header, $request.path, $context) instead of VTL.

EventBridge Integration

Integrates directly with EventBridge PutEvents API (see aws-samples/serverless-patterns/apigw-rest-api-eventbridge-sam). For a complete SAM template, see SAM Service Integration Templates — EventBridge.

• Use Type: AWS integration with URI arn:aws:apigateway:{region}:events:action/PutEvents

• Set required headers via RequestParameters (e.g., integration.request.header.X-Amz-Target: "'AWSEvents.PutEvents'", integration.request.header.Content-Type: "'application/x-amz-json-1.1'"). Alternative: set via VTL $context.requestOverride.header in the mapping template, but avoid applying the same header in both places (double-application causes 5XX)

• VTL mapping template transforms HTTP requests into EventBridge events. Use #foreach to batch multiple events from a single API call

• Input escaping: Use $util.escapeJavaScript($elem.Detail).replaceAll("\\'","'"), since escapeJavaScript over-escapes single quotes which breaks JSON; the replaceAll corrects this

• Supports custom event buses (not just default); pass bus name via !Sub in the mapping template

• Lambda authorizer can return custom:clientId to enrich events with caller identity

• Request validation via API Gateway models

• Use PassthroughBehavior: NEVER or WHEN_NO_TEMPLATES to reject unmatched content types. Avoid the default WHEN_NO_MATCH which passes malformed payloads through to the backend service

• EventBridge rules route events to Kinesis Data Firehose, Lambda, or API destinations

• Gotcha: EventBridge does not add newlines between records when forwarding to Firehose; use \n in InputTemplate

• Gotcha: PutEvents can succeed (200) with FailedEntryCount > 0 (partial failures are silent). Check $input.path('$.FailedEntryCount') in the response template and return an error status if non-zero

SQS Integration (Async Buffer)

Integrates directly with SQS SendMessage API to decouple producers from consumers (see aws-samples/serverless-patterns/apigw-sqs-lambda-iot). For a complete SAM template, see SAM Service Integration Templates — SQS.

• Use Type: AWS integration with URI arn:aws:apigateway:{region}:sqs:path/{account-id}/{queue-name}

• Two protocol options:

  • AWS query protocol: Set Content-Type: 'application/x-www-form-urlencoded' header in integration request. Mapping template: Action=SendMessage&MessageBody=$util.urlEncode($input.body)

  • AWS JSON protocol: Set Content-Type: 'application/x-amz-json-1.0' and X-Amz-Target: 'AmazonSQS.SendMessage' headers. Pass JSON body with QueueUrl and MessageBody

• Set PassthroughBehavior: NEVER to reject requests that don't match any mapping template (returns 415 Unsupported Media Type)

• Always use $util.urlEncode() with the query protocol; special characters in the message body cause AccessDenied errors without encoding

• FIFO queues: Append MessageGroupId to the mapping template: Action=SendMessage&MessageGroupId=$context.extendedRequestId&MessageBody=$util.urlEncode($input.body). Enable content-based deduplication on the queue, or add MessageDeduplicationId explicitly

• KMS-encrypted queues: IAM execution role needs kms:GenerateDataKey and kms:Decrypt on the queue's KMS key, otherwise KMS.AccessDeniedException

• Lambda consumer processes messages from SQS at its own pace, with built-in retry and DLQ support

SNS Integration (Fan-Out / Pub-Sub)

Integrates directly with SNS Publish API for fan-out to multiple subscribers (see aws-samples/serverless-patterns/apigw-websocket-api-sns):

• Use Type: AWS integration with URI arn:aws:apigateway:{region}:sns:action/Publish

• Uses AWS query protocol: Set Content-Type: 'application/x-www-form-urlencoded' header in integration request

• VTL mapping template: Action=Publish&TopicArn=$util.urlEncode("${TopicArn}")&Message=$util.urlEncode(...); always URL-encode both the TopicArn and Message

• Enrich messages with API Gateway context: $context.connectionId (WebSocket), $context.requestTimeEpoch, $context.identity.sourceIp

• Request validation: Use API Gateway models to validate the message body before publishing, ensuring only well-formed messages reach SNS

• Subscribers receive messages independently: Lambda, SQS, HTTP/S endpoints, email, SMS. One API call fans out to all

• KMS-encrypted topics: IAM execution role needs kms:GenerateDataKey and kms:Decrypt on the topic's KMS key

• Message attributes: Use indexed query parameters for subscription filter policies: MessageAttributes.entry.1.Name=eventType&MessageAttributes.entry.1.Value.DataType=String&MessageAttributes.entry.1.Value.StringValue=.... Required for SNS subscription filtering in fan-out architectures

• FIFO topics: Append MessageGroupId (required) and optionally MessageDeduplicationId to the mapping template, same pattern as SQS FIFO queues

• IAM execution role needs sns:Publish scoped to the specific topic ARN

DynamoDB Integration (Write-Through with Streams)

Integrates directly with DynamoDB APIs for full CRUD without Lambda. For complete SAM templates (OpenAPI-based and inline), see SAM Service Integration Templates — DynamoDB Full CRUD.

• Use Type: AWS integration with URI arn:aws:apigateway:{region}:dynamodb:action/{action} (supports GetItem, PutItem, UpdateItem, DeleteItem, Query, and Scan)

• VTL mapping template transforms HTTP request into DynamoDB JSON format:

  • Request template: Maps request body/parameters to DynamoDB item attributes with type descriptors (S, N, M, L, etc.)

  • Response template: Extracts DynamoDB response attributes into clean JSON for the client using $input.path('$.Item.attribute.S')

• Full CRUD pattern (see aws-samples/serverless-patterns/apigw-dynamodb-lambda-scheduler-ses-auto-deletion-sam):

  • Create: Use UpdateItem (not PutItem) with $context.requestId as auto-generated ID, eliminating client-side ID generation. Set ReturnValues: ALL_NEW to return the created item in the response

  • Read: GetItem with key from path parameter $input.params().path.id

  • Update: UpdateItem with UpdateExpression and ExpressionAttributeValues mapped from request body. Use ReturnValues: ALL_NEW to return the updated item

  • Delete: DeleteItem with ReturnValues: ALL_OLD to return the deleted item for confirmation

  • List: Scan with #foreach loop in response template to build JSON array from $inputRoot.Items. Always include a Limit parameter in the Scan template (e.g., "Limit": 25) to cap items per request; without it, a single API call can scan the entire table, consuming all provisioned capacity. Support pagination via ExclusiveStartKey mapped from a query parameter

• Request validation: Use x-amazon-apigateway-request-validator with OpenAPI schemas to validate request bodies at the gateway before reaching DynamoDB

• OpenAPI-based definition: Define the full API in a separate OpenAPI file and include via AWS::Include transform in the SAM template, keeping the API definition clean and separates API spec from infrastructure

• For async event processing, enable DynamoDB Streams on the table:

  • Stream triggers Lambda function on every insert/update/delete

  • Lambda processes changes asynchronously (enrichment, notifications, scheduling, cross-service sync)

  • Example chain: API Gateway → DynamoDB (Streams) → Lambda → EventBridge Scheduler → SES for scheduled email reminders

  • Stream view type options: KEYS_ONLY, NEW_IMAGE, OLD_IMAGE, NEW_AND_OLD_IMAGES; choose based on what the processor needs

• Gotcha: DynamoDB reserved keywords (datetime, email, status, name, type, data, etc.) require ExpressionAttributeNames with #placeholder syntax. This applies in VTL templates too, not just SDK calls

• Security: Never interpolate request input into DynamoDB expression strings (UpdateExpression, FilterExpression, ProjectionExpression). Hardcode expression structures in VTL and only map user input into ExpressionAttributeValues (:placeholder values). Interpolating into expressions allows callers to inject additional clauses that expose unintended attributes or modify other items

• Canary deployments for DynamoDB service integrations are managed at the API Gateway stage level (no Lambda alias to canary)

Kinesis Data Streams Integration (High-Throughput Ingestion)

Integrates directly with Kinesis Data Streams PutRecord/PutRecords APIs for high-volume data ingestion (see aws-samples/serverless-patterns/apigw-kinesis-lambda). For a complete SAM template, see SAM Service Integration Templates — Kinesis Data Streams.

• Use Type: AWS integration with URI arn:aws:apigateway:{region}:kinesis:action/{action} (e.g., action/PutRecord, action/PutRecords)

• Use PassthroughBehavior: WHEN_NO_TEMPLATES to ensure requests are only accepted when a matching mapping template exists

• VTL mapping template constructs the Kinesis payload:

  • StreamName: Target stream; can be hardcoded via !Sub or dynamic via path parameter ($input.params('stream-name'))

  • Data: Base64-encoded record data. Use $util.base64Encode() in VTL. Encode the full body ($input.body) or a specific JSON field ($input.json('$.Data'))

  • PartitionKey: Determines shard placement. Use a high-cardinality value from the request body (e.g., client ID) for even distribution across shards, or $context.requestId as a simple default for uniform distribution

• PutRecords for batching: VTL #foreach loop transforms an array of items in the request body into multiple Kinesis records in a single API call, reducing round-trips

• KMS-encrypted streams: IAM execution role needs kms:GenerateDataKey and kms:Decrypt on the stream's KMS key

• Downstream consumers: Lambda (event source mapping), Kinesis Data Firehose (delivery to S3/Redshift/OpenSearch), Kinesis Data Analytics, or custom KCL applications

• Shard limits: Each shard supports 1,000 records/s or 1 MB/s for writes and 2 MB/s for reads. Plan shard count based on expected ingestion rate. Use on-demand capacity mode to auto-scale shards

• Gotcha: PutRecord response includes ShardId and SequenceNumber; map these in the response template for client-side tracking if needed

• Gotcha: PutRecords can succeed (200) with FailedRecordCount > 0. Map $input.path('$.FailedRecordCount') in the response template so clients know to retry failed records

Step Functions Integration (Workflow Orchestration)

Integrates directly with Step Functions to orchestrate multi-step workflows without Lambda glue code. For complete SAM templates (REST and WebSocket), see SAM Service Integration Templates — Step Functions.

REST API → Step Functions (see aws-samples/serverless-patterns/apigw-rest-stepfunction):

• Two execution modes available:

  • Asynchronous (Standard workflow): action/StartExecution, which returns execution ARN immediately. Client does not wait for workflow completion. IAM role needs states:StartExecution

  • Synchronous (Express workflow): action/StartSyncExecution, which waits for workflow to complete and returns the result in the response. IAM role needs states:StartSyncExecution. Must complete within the API Gateway integration timeout (29s default, up to 300s for Regional/Private)

• VTL mapping template passes the request body as workflow input and the state machine ARN:

  Copy

  #set($data = $util.escapeJavaScript($input.json('$')).replaceAll("\\'","'"))
  {
    "input": "$data",
    "stateMachineArn": "${StateMachineArn}"
  }

WebSocket API → Step Functions (see aws-samples/serverless-samples/apigw-ws-integrations):

• Two execution modes via custom routes matched by routeSelectionExpression:

  • Synchronous (Express workflow): action/StartSyncExecution, which waits for workflow to complete and returns the result directly to the WebSocket client. Constrained by the 29-second WebSocket API integration timeout, not the 5-minute Express workflow maximum. Workflows exceeding 29 seconds will time out at the API Gateway level. Use for short-lived workflows where the client needs the result immediately

  • Asynchronous (Standard workflow): action/StartExecution, which returns the execution ARN immediately. Workflow pushes results back to the WebSocket client via the @connections Management API (POST https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}) using an HTTP task state or Lambda task. Pass $context.connectionId in the input so the workflow knows which client to notify

• VTL escaping for WebSocket: $util.escapeJavaScript($input.json("$.data")).replaceAll("\\'","'") (the replaceAll handles single quotes that escapeJavaScript over-escapes)

• WebSocket $connect/$disconnect routes can use direct DynamoDB integration (PutItem/DeleteItem) for connection tracking without Lambda

• IAM roles: states:StartSyncExecution for Express, states:StartExecution for Standard. Async workflow role also needs execute-api:ManageConnections to call back the WebSocket client

Express vs Standard workflows:

• Express (sync): Max 5 minutes, at-least-once execution, lower cost for high-volume short tasks. Good for synchronous REST/WebSocket responses within the API Gateway timeout

• Standard (async): Max 1 year, exactly-once execution, full execution history. Good for long-running orchestrations that push results via callback, webhook, or polling

Lambda durable functions as alternative: Durable functions are invoked as regular Lambda integrations (proxy or custom) — no Type: AWS service integration or VTL needed. See the aws-lambda-durable-functions skill for details.

S3 Integration (File Storage Proxy)

Acts as an S3 proxy for file upload, download, and listing without Lambda (see Developer Guide tutorial):

• Use Type: AWS integration with Action type: Use path override. API Gateway forwards requests to S3 REST API path-style (s3-host-name/{bucket}/{key})

• Resource structure: /{folder} maps to S3 bucket, /{folder}/{item} maps to S3 object. Map path parameters in integration request: method.request.path.folder → {bucket}, method.request.path.item → {object}

• Operations: GET on / lists buckets, GET on /{folder} lists objects in a bucket, GET on /{folder}/{item} downloads an object, PUT on /{folder}/{item} uploads an object

• Binary files (images, PDFs, etc.): Register media types in binaryMediaTypes (e.g., image/png), add Accept (download) and Content-Type (upload) headers to the method request, leave contentHandling unset (passthrough behavior); no mapping template for binary content types

• Payload limit: 10 MB max through API Gateway. For larger files, generate S3 presigned URLs via Lambda and have the client upload/download directly to S3 (presigned URLs cannot be generated from a direct service integration; Lambda is required)

• Response header mapping: Map integration.response.header.Content-Type, integration.response.header.Content-Length, and integration.response.header.Date to method response headers for proper content delivery

• S3 objects with / or special characters in the key must be URL-encoded in the request path (e.g., test/test.txt → test%2Ftest.txt)

• IAM execution role needs S3 permissions (s3:GetObject, s3:PutObject, s3:ListBucket) scoped to the specific bucket(s)

HTTP Integration (Proxy to HTTP Endpoints)

Forwards requests to any HTTP-accessible endpoint: ALB, NLB, ECS, EC2, on-premises servers, or external third-party APIs:

• Two modes:

  • HTTP_PROXY: Passes request through to the backend as-is and returns the backend response directly to the client. Minimal configuration, no VTL templates. Available on both REST and HTTP APIs

  • HTTP (non-proxy): Allows VTL mapping templates to transform request and response. REST API only

• VPC Link for private backends: Use connectionType: VPC_LINK to reach ALB, NLB, or Cloud Map services inside a VPC without exposing them to the internet. VPC Link v2 supports REST and HTTP APIs (targets ALB and NLB); WebSocket API uses VPC Link v1 (NLB only)

• Path and parameter passthrough: Map URL path parameters, query strings, and headers from the method request to the integration request. Use {proxy+} greedy path parameter for catch-all routing

• TLS to backend: API Gateway validates the backend's TLS certificate by default. If the backend uses a self-signed or private CA certificate, set insecureSkipVerification: true on the integration (testing/development only; not recommended for production). Provide the full certificate chain on the backend for proper validation

• Timeouts: Configure timeoutInMillis on the integration (50ms–29s for REST, 30s hard limit for HTTP API). For backends that may exceed this, consider async patterns

• Connection reuse: API Gateway reuses connections to HTTP backends by default for lower latency on subsequent requests

• No automatic retries: API Gateway does not retry failed HTTP integration requests. If the backend returns 5xx or the connection times out, the error is returned directly to the client. Implement retry logic on the client side or use SQS as a buffer

Mock Integration (No Backend)

Returns responses directly from API Gateway without calling any backend:

• Use Type: MOCK (no integration URI, no IAM role, no backend needed)

• Health check endpoints: Return 200 on /health for load balancer or monitoring checks

• CORS preflight: Handle OPTIONS requests with appropriate CORS headers without invoking Lambda

• API prototyping: Define request/response contracts before backends are built. Consumers can develop against the mock

• Static responses: Return fixed JSON/XML based on request parameters using VTL mapping templates

• VTL request template must return {"statusCode": 200} (or appropriate code) to set the integration response status

• Map different status codes using IntegrationResponses with selection patterns

Common Patterns

• IAM execution role: Every direct service integration requires an IAM role with the specific action permission (e.g., sqs:SendMessage, dynamodb:PutItem, events:PutEvents, kinesis:PutRecord, states:StartExecution). Pass the role ARN in the integration Credentials field

• Request validation at the gateway: Use API Gateway request validators (models) to reject invalid requests before they reach the backend service, reducing cost and protects downstream services

• Response mapping: Transform raw AWS service responses into clean API responses using VTL response templates. Map HTTP status codes for error cases in IntegrationResponses

• Lambda invocations support sync and async: API Gateway Lambda integrations default to synchronous invocation (wait for response). For asynchronous invocation (fire-and-forget, returns 200 immediately while Lambda processes in background), set X-Amz-Invocation-Type: 'Event' in the integration request HTTP headers (see re:Post guide). Async invocation supports Lambda's built-in retry (up to 2 retries) and dead-letter queues. REST API supports this natively via non-proxy integration; HTTP API only supports proxy integrations for Lambda so X-Amz-Invocation-Type cannot be set — use a proxy Lambda that invokes the target Lambda asynchronously via the SDK

• Prevent backend bypass (zero trust): Ensure backends can only be reached through API Gateway, not invoked or accessed directly. Apply defense in depth per integration type:

  • Lambda: Restrict Lambda resource policies to allow invocations only from the API Gateway source ARN

  • VPC Link targets (ALB/NLB): Use security groups on the load balancer to accept traffic only from the VPC Link's ENIs, not from arbitrary sources

  • HTTP integrations: Use mutual TLS, API keys, or signed requests between API Gateway and the backend to authenticate the caller

  • Direct service integrations (SQS, DynamoDB, etc.): The IAM execution role scopes access — ensure the role is only assumable by API Gateway (apigateway.amazonaws.com principal) and follows least-privilege for the specific resources

• Parameter overriding (REST API): Override request/response parameters and status codes at method level:

  • RequestParameters in Integration: Map method request values to integration request values

  • ResponseParameters in IntegrationResponses: Map integration response values to method response values

  • Override response status: #set($context.responseOverride.status = 400) in VTL

  • Override request headers: $context.requestOverride.header.<name>

  • Gotcha: Applying override to same parameter twice causes 5XX. Build in a variable first, apply at end

• Binary media types: API Gateway request and response payloads can be text or binary (JPEG, GZip, XML, PDF, etc.). Configure binaryMediaTypes on the API, specifying content types treated as binary (e.g., image/png, application/octet-stream). Avoid */* wildcard: it treats ALL responses as binary, breaking Lambda proxy integrations that return JSON:

  • Lambda proxy integrations: Lambda must return the response body as base64-encoded and set isBase64Encoded: true. The API must have matching binaryMediaTypes configured. Client sends Accept header matching a binary media type

  • Non-proxy integrations: Set binaryMediaTypes on the API, or use contentHandling on the Integration and IntegrationResponse resources: CONVERT_TO_BINARY (base64-decode text to binary), CONVERT_TO_TEXT (base64-encode binary to text), or undefined (passthrough)

• Local testing limitation: sam local start-api does not support Type: AWS service integrations; it only supports Lambda proxy/non-proxy integrations. Test direct service integrations by deploying to a dev stage and using the API Gateway test console (AWS Console → method → Test) to validate VTL mapping templates against sample requests without a full deployment cycle