API Gateway

API Gateway Fundamentals

Amazon API Gateway is a fully managed service for creating, publishing, maintaining, monitoring, and securing APIs.

API Types

Create a REST API

# Create REST API
aws apigateway create-rest-api \
  --name my-api \
  --description "My REST API" \
  --endpoint-configuration types=REGIONAL

# Create resource (path)
aws apigateway create-resource \
  --rest-api-id abc123 \
  --parent-id abc123_rootId \
  --path-part items

# Create GET method
aws apigateway put-method \
  --rest-api-id abc123 \
  --resource-id xyz789 \
  --http-method GET \
  --authorization-type NONE

# Create Lambda integration
aws apigateway put-integration \
  --rest-api-id abc123 \
  --resource-id xyz789 \
  --http-method GET \
  --type AWS_PROXY \
  --integration-http-method POST \
  --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:my-function/invocations

Create HTTP API (Simpler)

# Create HTTP API
aws apigatewayv2 create-api \
  --name my-http-api \
  --protocol-type HTTP

# Create Lambda integration
aws apigatewayv2 create-integration \
  --api-id xxx \
  --integration-type AWS_PROXY \
  --integration-uri arn:aws:lambda:us-east-1:xxx:function:my-function

# Create route
aws apigatewayv2 create-route \
  --api-id xxx \
  --route-key "GET /items"

Request/Response Mapping

Request Validation

# Create request validator
aws apigateway update-rest-api \
  --rest-api-id abc123 \
  --patch-operations op=replace,path=/requestValidators,value='[{"name":"full","validateRequestBody":true,"validateRequestParameters":true}]'

# Create model schema
aws apigateway create-model \
  --rest-api-id abc123 \
  --name CreateUserModel \
  --content-type application/json \
  --schema '{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "required": ["name", "email"],
    "properties": {
      "name": {"type": "string", "minLength": 1},
      "email": {"type": "string", "format": "email"},
      "age": {"type": "integer", "minimum": 0}
    }
  }'

Integration Request/Response Mapping

# Mapping template for Lambda proxy
aws apigateway put-integration-response \
  --rest-api-id abc123 \
  --resource-id xyz789 \
  --http-method GET \
  --status-code 200

# Integration response mapping template
aws apigateway update-integration \
  --rest-api-id abc123 \
  --integration-id xxx \
  --patch-operations 'op=replace,path=/requestTemplates/application~1json,value={"body": $input.json("$")} Content-Type: application/json'

HTTP API Payload Format

{
  "version": "2.0",
  "routeKey": "GET /items",
  "rawPath": "/items",
  "rawQueryString": "limit=10",
  "headers": {
    "content-type": "application/json"
  },
  "requestContext": {
    "http": {
      "method": "GET",
      "path": "/items",
      "sourceIp": "203.0.113.1"
    },
    "authorizer": {
      "jwt": {
        "claims": {
          "sub": "user-123"
        }
      }
    }
  },
  "body": null,
  "isBase64Encoded": false
}

Authentication and Authorization

Cognito User Pool Authorizer

# Create authorizer
aws apigateway create-authorizer \
  --rest-api-id abc123 \
  --name CognitoAuth \
  --type COGNITO_USER_POOLS \
  --provider-arns arn:aws:cognito-idp:us-east-1:xxx:userpool/us-east-1_xxx \
  --identity-source method.request.header.Authorization

# Attach to method
aws apigateway update-method \
  --rest-api-id abc123 \
  --resource-id xyz789 \
  --http-method GET \
  --patch-operations 'op=replace,path=/authorizationType,value=COGNITO_USER_POOLS' 'op=replace,path=/authorizerId,value=xxx'

Lambda Authorizer

# Lambda authorizer function
def lambda_handler(event, context):
    token = event['authorizationToken']
    
    # Validate token
    if token == 'valid-token':
        return {
            'isAuthorized': True,
            'context': {
                'userId': 'user-123',
                'role': 'admin'
            }
        }
    
    return {
        'isAuthorized': False
    }

# Create Lambda authorizer
aws apigateway create-authorizer \
  --rest-api-id abc123 \
  --name LambdaAuth \
  --type TOKEN \
  --authorizer-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:xxx:function:auth-function/invocations \
  --authorizer-result-ttl-in-seconds 300

API Keys and Usage Plans

# Create API key
aws apigateway create-api-key \
  --name my-api-key \
  --enabled

# Create usage plan
aws apigateway create-usage-plan \
  --name my-usage-plan \
  --throttle burstLimit=1000,rateLimit=500 \
  --quota limit=10000,period=MONTH

# Associate key with usage plan
aws apigateway create-usage-plan-key \
  --usage-plan-id xxx \
  --key-id yyy \
  --key-type API_KEY

Deployment and Stages

Deploy API

# Create deployment
aws apigateway create-deployment \
  --rest-api-id abc123 \
  --stage-name prod \
  --stage-description "Production" \
  --description "Initial deployment"

# Create stage manually
aws apigateway create-stage \
  --rest-api-id abc123 \
  --stage-name v1 \
  --deployment-id xxx \
  --description "Version 1"

# Enable access logging
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations 'op=replace,path=/accessLogSettings/destinationArn,value=arn:aws:logs:us-east-1:xxx:log-group:api-gateway-logs'

# Enable caching
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations 'op=replace,path=/cacheClusterEnabled,value=true' 'op=replace,path=/cacheClusterSize,value=1.6'

Throttling

# Set stage-level throttling
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations 'op=replace,path=/methodSettings/~/GET/throttlingRateLimit,value=1000' 'op=replace,path=/methodSettings/~/GET/throttlingBurstLimit,value=500'

# Account-level throttling
aws apigateway update-account \
  --patch-operations 'op=replace,path=/throttleSettings/rateLimit,value=10000' 'op=replace,path=/throttleSettings/burstLimit,value=5000'

Stage Variables

# Set stage variables
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations 'op=add,path=/variables/lambdaAlias,value=prod' 'op=add,path=/variables/region,value=us-east-1'

# Reference in integration URI
# arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/${stageVariables.lambdaAlias}/invocations

API Gateway Best Practices and Cost

Architecture Patterns

┌─────────────────────────────────────────────────────────────┐
│                    Serverless API                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Client ──▶ API Gateway ──┬──▶ Lambda (Auth)               │
│                           ├──▶ Lambda (Business Logic)     │
│                           └──▶ DynamoDB                     │
│                                                             │
│  Features:                                                  │
│  • Request validation                                       │
│  • Caching                                                  │
│  • Throttling                                               │
│  • API keys                                                 │
│  • Custom domains                                           │
└─────────────────────────────────────────────────────────────┘

Cost Optimization

# Use HTTP API for simpler use cases (70% cheaper)
aws apigatewayv2 create-api \
  --name my-http-api \
  --protocol-type HTTP

# Enable caching to reduce backend calls
aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations 'op=replace,path=/cacheClusterEnabled,value=true' 'op=replace,path=/cacheClusterSize,value=0.5'

Custom Domain

# Request ACM certificate
aws acm request-certificate \
  --domain-name api.example.com

# Create custom domain
aws apigateway create-domain-name \
  --domain-name api.example.com \
  --regional-certificate-arn arn:aws:acm:us-east-1:xxx:certificate/yyy \
  --endpoint-configuration types=REGIONAL

# Map base path to API
aws apigateway create-base-path-mapping \
  --domain-name api.example.com \
  --rest-api-id abc123 \
  --stage prod