API Gateway is the managed front door for APIs: routing, auth, throttling, caching and monitoring in front of Lambda or any backend. Overview is in 5. AWS Networking and serverless context in 6. AWS Developer Services and Serverless.

API types at a glance

Pick HTTP API for simple proxy-to-Lambda or backend routes; pick REST API when you need caching, usage plans, validation, WAF or private endpoints.

flowchart LR
    C[Client] --> DN[Custom domain + ACM cert]
    DN --> AG[API Gateway: stage]
    AG --> AU{Authorizer}
    AU -- ok --> TH[Throttling / validation / cache]
    TH --> IN[Integration]
    IN --> L[Lambda]
    IN --> H[HTTP backend via VPC link]
    IN --> S[AWS service]

Building Blocks

Integration types

Lambda proxy handler:

import json

def handler(event, context):
    order_id = event["pathParameters"]["id"]
    return {
        "statusCode": 200,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({"id": order_id, "status": "shipped"}),
    }

HTTP API uses payload format 2.0 (similar shape, with requestContext.http).

Endpoint Types (REST)

Authentication and Authorisation

• API keys are for identifying and metering clients, not for security. Combine with a real authorizer
• Authorise per route and scope; do not rely on hidden URLs. See 2. Web Application Security

Throttling, Quotas and Caching

Integration timeout defaults to about 29 seconds (check current quotas); long jobs should be asynchronous (return 202 and process via SQS / Step Functions).

Request and Response Handling

• Request validation (REST): reject bad bodies, query strings or headers before they reach Lambda, using JSON Schema models
• Mapping templates (REST, VTL): reshape payloads, for example turn a request into a DynamoDB call
• CORS: HTTP API enables it in one setting; REST needs an OPTIONS method and CORS headers on responses
• Gateway responses: customise error bodies (4XX, 5XX, throttling)
• Binary media types for images and files
• Payload limit about 10 MB

# OpenAPI / SAM style (HTTP API)
Events:
  GetOrder:
    Type: HttpApi
    Properties:
      Path: /orders/{id}
      Method: GET

Stages, Deployments and Releases

• Stages hold their own stage variables, logging and throttling (e.g. dev points at a dev Lambda alias)
• REST: edit, then create a deployment to a stage. HTTP API supports auto-deploy
• Canary releases (REST): send a percentage of traffic to the new deployment, then promote
• Pair Lambda aliases (live, beta) with stage variables for safe rollouts
• Export and import with OpenAPI to keep the API in source control (Infrastructure as Code)

Custom Domains

1. ACM certificate (Regional APIs: same Region; edge-optimized: us-east-1)
2. Create the custom domain name, choose TLS version
3. API mapping: api.example.com/v1 to API + stage
4. Route 53 alias record to the domain's target (AWS Route 53 Deep Dive)

Security

• WAF (REST): rate limits, managed rules, geo blocks
• Resource policies and private endpoints for internal APIs
• TLS only; choose a minimum TLS version on the custom domain
• Least-privilege roles for integrations: 2. AWS IAM and Security
• Validate input; return generic errors; no stack traces

Logging and Monitoring

Compare Latency (total) with IntegrationLatency (backend only) to see whether time is spent in API Gateway or in your code.

API Gateway vs Alternatives

Troubleshooting