Amazon API Gateway: Build, Deploy, and Manage APIs

You’ve built a killer microservice. It’s fast, clean, and tested. Then you expose it to the internet and within hours it’s drowning in retries, DDoS-adjacent traffic, and clients complaining about 5xx errors. That’s the moment you realize: your API needs a bouncer, not just a door. Amazon API Gateway is that bouncer — but it’s also the coat check, the bartender, and the cleanup crew. It’s the single most underutilized service in AWS for teams that think they can just slap an ALB in front of a Lambda and call it a day. They’re wrong. API Gateway gives you request throttling per client, response caching, request validation, API versioning, and WebSocket support — all without provisioning a single server. But here’s the catch: misconfigure it, and you’ll either leak data through overly permissive CORS or burn money on unnecessary Lambda invocations. I’ve seen teams deploy APIs that cost 10x more than needed because they ignored caching or used the wrong endpoint type. This isn’t theory — it’s production. Let’s fix that.

Why API Gateway?

API Gateway is the front door for your serverless APIs. It handles request routing, authentication, rate limiting, and response transformation. Without it, you'd need to build these capabilities yourself — and you'd likely get them wrong. In production, API Gateway sits between your clients and your backend services (Lambda, HTTP, or AWS services). It abstracts away the complexity of managing infrastructure for API hosting, letting you focus on business logic. But it's not magic: misconfiguring throttling, caching, or authorization can bring down your service. We'll walk through building a production-ready API from scratch, covering the pitfalls that bite teams in staging.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      DefinitionBody:
        swagger: '2.0'
        info:
          title: MyAPI
        paths:
          /items:
            get:
              x-amazon-apigateway-integration:
                type: aws_proxy
                httpMethod: POST
                uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetItemsFunction.Arn}/invocations
              responses: {}
  GetItemsFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: index.handler
      Runtime: nodejs18.x
      Events:
        Api:
          Type: Api
          Properties:
            RestApiId: !Ref MyApi
            Path: /items
            Method: GET

Choosing the Right API Type: REST vs. HTTP vs. WebSocket

API Gateway offers three API types: REST, HTTP, and WebSocket. REST APIs are feature-rich with request validation, caching, and usage plans. HTTP APIs are simpler, cheaper, and faster — ideal for most new projects. WebSocket APIs enable real-time two-way communication. For a typical CRUD service, start with HTTP APIs. They have lower latency and cost less per request. But if you need advanced features like API keys, usage plans, or request validation, you'll need REST APIs. In production, we've seen teams pick REST APIs out of habit and pay 3x more for no benefit. Choose HTTP APIs unless you have a specific need for REST features.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-09
Resources:
  MyHttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: prod
      DefinitionBody:
        openapi: '3.0.1'
        info:
          title: MyHttpApi
        paths:
          /items:
            get:
              x-amazon-apigateway-integration:
                type: aws_proxy
                httpMethod: POST
                payloadFormatVersion: '2.0'
                uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetItemsFunction.Arn}/invocations
  GetItemsFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: index.handler
      Runtime: nodejs18.x
      Events:
        HttpApi:
          Type: HttpApi
          Properties:
            ApiId: !Ref MyHttpApi
            Path: /items
            Method: GET

Authentication and Authorization: IAM, Cognito, or Lambda Authorizer

API Gateway supports three authorization methods: IAM, Cognito User Pools, and Lambda authorizers (custom). IAM is best for internal services where you can use AWS credentials. Cognito is ideal for user-facing apps with sign-up/sign-in. Lambda authorizers give you full control — you can validate JWT tokens, call external identity providers, or implement custom logic. In production, use Cognito for user authentication and Lambda authorizers for fine-grained access control (e.g., checking user roles). Avoid IAM for external APIs because it requires clients to sign requests with AWS SigV4, which is complex for mobile apps.

exports.handler = async (event) => {
    const token = event.authorizationToken;
    if (!token) {
        throw new Error('Unauthorized');
    }
    // Validate token (e.g., JWT verification)
    try {
        const decoded = verifyToken(token); // your verification logic
        return {
            principalId: decoded.sub,
            policyDocument: {
                Version: '2012-10-17',
                Statement: [{
                    Action: 'execute-api:Invoke',
                    Effect: 'Allow',
                    Resource: event.methodArn
                }]
            },
            context: {
                userId: decoded.sub,
                role: decoded['cognito:groups']
            }
        };
    } catch (err) {
        throw new Error('Unauthorized');
    }
};

Request Validation and Transformation

API Gateway can validate requests before they reach your backend. Define a JSON Schema for your request body, query parameters, and headers. Invalid requests are rejected with a 400 error, saving your backend from processing garbage. You can also transform requests and responses using mapping templates (Velocity Template Language). For example, you can strip sensitive fields, change the response format, or combine multiple backend responses. In production, always enable request validation. It's a cheap way to enforce contracts and reduce errors. But beware: VTL mapping templates are hard to debug. Prefer Lambda proxy integration and handle transformations in your code.

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      DefinitionBody:
        swagger: '2.0'
        paths:
          /items:
            post:
              x-amazon-apigateway-request-validator: 'Validate body'
              x-amazon-apigateway-request-validators:
                Validate body:
                  validateRequestBody: true
                  validateRequestParameters: false
              parameters:
                - name: body
                  in: body
                  required: true
                  schema:
                    type: object
                    required:
                      - name
                    properties:
                      name:
                        type: string
              responses:
                '200':
                  description: OK

Throttling, Quotas, and Usage Plans

API Gateway allows you to throttle requests per client using usage plans and API keys. You can set rate limits (requests per second) and burst limits (concurrent requests). For REST APIs, you can also set quotas (requests per day/week/month). This is critical for protecting your backend from abuse or accidental spikes. In production, always set a default throttle on your API stage. Use usage plans for different tiers of customers. But be careful: throttling returns 429 Too Many Requests. Your clients must handle this gracefully. Also, API keys are not secure — they can be stolen. Combine with authentication for real security.

  UsagePlan:
    Type: AWS::ApiGateway::UsagePlan
    Properties:
      ApiStages:
        - ApiId: !Ref MyApi
          Stage: prod
      Throttle:
        BurstLimit: 20
        RateLimit: 10
      Quota:
        Limit: 1000
        Period: DAY
  ApiKey:
    Type: AWS::ApiGateway::ApiKey
    Properties:
      Enabled: true
      StageKeys:
        - RestApiId: !Ref MyApi
          StageName: prod
  UsagePlanKey:
    Type: AWS::ApiGateway::UsagePlanKey
    Properties:
      KeyId: !Ref ApiKey
      KeyType: API_KEY
      UsagePlanId: !Ref UsagePlan

Caching to Reduce Latency and Cost

API Gateway can cache responses from your backend. When enabled, it stores responses for a configurable TTL (default 300 seconds). Subsequent identical requests are served from cache, reducing latency and backend load. Caching is especially useful for read-heavy endpoints with infrequently changing data. You can also invalidate cache programmatically by sending a request with Cache-Control: max-age=0 header. In production, enable caching for GET endpoints that return static or semi-static data. But be careful: cache size and cost scale with the number of distinct responses. Monitor cache hit ratio and adjust TTL accordingly.

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /items
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300

Monitoring and Logging with CloudWatch

API Gateway integrates with CloudWatch for metrics and logs. You can monitor request count, latency, error rates, and throttling. Enable detailed CloudWatch metrics and execution logs (with full request/response data) for debugging. In production, set up alarms for 4xx and 5xx errors, high latency, and throttling. Use log groups to search for specific errors. But beware: execution logs can be expensive if you have high traffic. Sample logs (e.g., log every 100th request) to reduce cost. Also, enable access logs to capture who called what and when.

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      AccessLogSetting:
        DestinationArn: !GetAtt ApiLogGroup.Arn
        Format: '{"requestId":"$context.requestId","ip":"$context.identity.sourceIp","caller":"$context.identity.caller","user":"$context.identity.user","requestTime":"$context.requestTime","httpMethod":"$context.httpMethod","resourcePath":"$context.resourcePath","status":$context.status,"protocol":"$context.protocol","responseLength":$context.responseLength}'
  ApiLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      RetentionInDays: 30

Deploying and Managing Stages

API Gateway uses stages to manage different environments (dev, staging, prod). Each stage has its own configuration: throttling, caching, logging, and domain name. You can deploy a stage from an API snapshot. In production, use a canary deployment for gradual rollouts. Deploy a new version to a canary stage, route a percentage of traffic to it, and monitor for errors before promoting. This reduces risk of breaking changes. Also, use stage variables to pass environment-specific values (e.g., Lambda function alias) to your integration. Never hardcode environment-specific values.

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CanarySetting:
        PercentTraffic: 10
        StageVariableOverrides:
          lambdaAlias: canary
      DefinitionBody:
        ...
      Variables:
        lambdaAlias: prod

Custom Domains and SSL/TLS

API Gateway assigns a default domain like https://api-id.execute-api.region.amazonaws.com. For production, you'll want a custom domain (e.g., api.yourcompany.com). You can create a custom domain name in API Gateway and associate it with an ACM certificate. API Gateway manages SSL termination. You can also use Route 53 alias records to point your domain to the API Gateway endpoint. In production, always use a custom domain. It's more professional and allows you to change the backend without changing the client URL. Also, enforce TLS 1.2 or higher for security.

  CustomDomain:
    Type: AWS::ApiGateway::DomainName
    Properties:
      DomainName: api.yourcompany.com
      CertificateArn: arn:aws:acm:us-east-1:123456789012:certificate/abc-123
      EndpointConfiguration:
        Types:
          - REGIONAL
  BasePathMapping:
    Type: AWS::ApiGateway::BasePathMapping
    Properties:
      DomainName: !Ref CustomDomain
      RestApiId: !Ref MyApi
      Stage: prod

Error Handling and Response Mapping

API Gateway can map backend errors to standard HTTP responses. By default, Lambda errors (e.g., unhandled exceptions) return a 502 Bad Gateway. You can customize this using gateway responses for 4xx and 5xx errors. For example, map a Lambda timeout to a 504 Gateway Timeout. You can also define custom error responses with a JSON body. In production, always define custom gateway responses. They provide consistent error formats for clients. Also, use the x-amzn-ErrorType header for machine-readable errors. Avoid exposing stack traces in error responses.

  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      GatewayResponses:
        DEFAULT_4XX:
          ResponseParameters:
            gatewayresponse.header.x-amzn-ErrorType: "'InvalidRequest'"
          ResponseTemplates:
            application/json: '{"message":"Invalid request","error":"$context.error.messageString"}'
        DEFAULT_5XX:
          ResponseParameters:
            gatewayresponse.header.x-amzn-ErrorType: "'InternalError'"
          ResponseTemplates:
            application/json: '{"message":"Internal server error"}'

Testing and Debugging with Postman and curl

Before deploying to production, test your API thoroughly. Use tools like Postman or curl to send requests and inspect responses. Test different HTTP methods, headers, query parameters, and request bodies. Verify authentication works (e.g., pass a valid token). Test error cases: missing required fields, invalid data, expired tokens. Also, test throttling by sending many requests quickly. In production, set up integration tests that run against a staging API. Automate these tests in your CI/CD pipeline. This catches regressions before they reach production.

# Test GET /items
curl -X GET https://api-id.execute-api.us-east-1.amazonaws.com/prod/items \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test POST /items with valid body
curl -X POST https://api-id.execute-api.us-east-1.amazonaws.com/prod/items \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"test"}'

# Test validation error (missing name)
curl -X POST https://api-id.execute-api.us-east-1.amazonaws.com/prod/items \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

# Test throttling (send 20 requests quickly)
for i in {1..20}; do
  curl -X GET https://api-id.execute-api.us-east-1.amazonaws.com/prod/items &
done
wait

Production Best Practices Recap

To recap: start with HTTP APIs unless you need REST features. Use Cognito or Lambda authorizers for auth. Enable request validation. Set throttling and usage plans. Use caching for read-heavy endpoints. Monitor with CloudWatch alarms. Use custom domains. Implement canary deployments. Customize error responses. Automate testing. And always use infrastructure as code. These practices will save you from common production failures: cost spikes, latency issues, security breaches, and downtime. API Gateway is powerful, but it requires careful configuration. Treat it as a critical piece of infrastructure, not a simple proxy.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-09
Resources:
  MyHttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: prod
      DefinitionBody:
        openapi: '3.0.1'
        info:
          title: MyApi
        paths:
          /items:
            get:
              x-amazon-apigateway-integration:
                type: aws_proxy
                httpMethod: POST
                payloadFormatVersion: '2.0'
                uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GetItemsFunction.Arn}/invocations
      AccessLogSetting:
        DestinationArn: !GetAtt ApiLogGroup.Arn
        Format: '{"requestId":"$context.requestId","status":$context.status}'
  ApiLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      RetentionInDays: 30
  GetItemsFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: index.handler
      Runtime: nodejs18.x
      Events:
        HttpApi:
          Type: HttpApi
          Properties:
            ApiId: !Ref MyHttpApi
            Path: /items
            Method: GET