API Gateway: The Complete Guide — AWS vs Azure, Real-World Examples, and What Actually Breaks

Mobile App ──────────────── Lambda: bookAppointment
Mobile App ──────────────── Lambda: getCallLogs
Mobile App ──────────────── Lambda: verifyInsurance
Web App    ──────────────── Lambda: bookAppointment
Web App    ──────────────── Lambda: getCallLogs
3rd Party  ──────────────── Lambda: getCallLogs

Mobile App ─┐
Web App    ─┼──── API Gateway ──── Lambda: bookAppointment
3rd Party  ─┘         │
                       ├────────── Lambda: getCallLogs
                       └────────── Lambda: verifyInsurance

One front door handles everything:
  Auth · Rate Limiting · Logging · CORS · Routing · Versioning · Caching

Client Request
      ↓
① METHOD + ROUTE MATCHING
  "Does POST /appointments/{id}/cancel exist?"
  No → 404 immediately. Lambda never invoked.
      ↓
② AUTHORISER
  Validates JWT or calls Lambda Authoriser
  Invalid token → 401. Lambda never invoked.
      ↓
③ REQUEST VALIDATION  (REST API only)
  Required headers present? Body matches schema?
  Invalid → 400. Lambda never invoked.
      ↓
④ REQUEST TRANSFORMATION  (REST API only)
  Reshape the incoming JSON, inject context variables
      ↓
⑤ LAMBDA INVOCATION
  Lambda receives event, processes, returns response
      ↓
⑥ RESPONSE TRANSFORMATION  (REST API only)
  Reshape Lambda output to client-expected format
      ↓
⑦ RESPONSE TO CLIENT
  + CORS headers added
  + CloudWatch log entry written
  + X-Ray trace segment closed

Client → HTTPS → HTTP API → Lambda → Response
                    ↑
        JWT validation, CORS, routing — that is it

POST https://api.mybcat.com/appointments        → book-appointment Lambda
GET  https://api.mybcat.com/appointments/{id}   → get-appointment Lambda
PUT  https://api.mybcat.com/appointments/{id}/cancel → cancel-appointment Lambda
GET  https://api.mybcat.com/practices/{id}/slots    → get-slots Lambda

Practice A — Small Practice:
  API Key: key_p001_abc123
  Quota:   1,000 requests/day
  Throttle: 50 requests/second burst

Practice B — Large Practice:
  API Key: key_p002_xyz789
  Quota:   50,000 requests/day
  Throttle: 200 requests/second burst

Practice C — Enterprise:
  API Key: key_p003_enterprise
  Quota:   Unlimited
  Throttle: 500 requests/second burst

Result:
  Practice A exceeds 1,000 → 429 Too Many Requests
  Practice B is completely unaffected
  Your Lambda never sees the excess traffic from Practice A

GET /practices/p001/insurance-plans
  → First request in 5 minutes: Lambda called, result cached
  → Next 300 requests in 5 minutes: served from API Gateway cache
  → Lambda invocations: 1 instead of 301
  → 99.7% reduction in Lambda calls for stable reference data

Cache key includes:
  - The route path
  - Any query parameters you specify
  - Any headers you specify (e.g., practice_id)

Client browser opens connection:
  WSS://realtime.mybcat.com/

API Gateway:
  1. Assigns a unique connectionId: "Abc123XYZ"
  2. Calls your $connect Lambda — store connectionId in DynamoDB
  3. Keeps the connection open
  4. When client sends a message → routes to Lambda based on action field
  5. When client disconnects → calls $disconnect Lambda — clean up DynamoDB

When a backend event happens (call ended):
  Lambda fetches all connectionIds for practiceId "p001" from DynamoDB
  Posts message to each connection via API Gateway Management API
  Client receives message instantly — no request was made

# Backend pushes a message to all connected dashboards for a practice
def notify_practice_dashboards(practice_id: str, event: dict):
    apigw = boto3.client(
        'apigatewaymanagementapi',
        endpoint_url='https://abc123.execute-api.us-east-1.amazonaws.com/prod'
    )

    connections = get_active_connections(practice_id)  # DynamoDB query

    for conn_id in connections:
        try:
            apigw.post_to_connection(
                ConnectionId=conn_id,
                Data=json.dumps(event)
            )
        except apigw.exceptions.GoneException:
            # Browser was closed — remove stale connection
            delete_connection(conn_id)

resource "aws_apigatewayv2_authorizer" "cognito" {
  api_id           = aws_apigatewayv2_api.main.id
  authorizer_type  = "JWT"
  identity_sources = ["$request.header.Authorization"]
  name             = "cognito-jwt"

  jwt_configuration {
    audience = [aws_cognito_user_pool_client.app.id]
    issuer   = "https://cognito-idp.${var.region}.amazonaws.com/${aws_cognito_user_pool.main.id}"
  }
}

# Lambda Authoriser — custom auth logic
def handler(event, context):
    token = event['authorizationToken'].replace('Bearer ', '')

    try:
        payload = jwt.decode(token, PUBLIC_KEY, algorithms=['RS256'])

        # Custom check: is this practice's subscription active?
        practice_id = payload['custom:practice_id']
        if not is_subscription_active(practice_id):
            raise Exception('Unauthorized')  # returns 403

        # Return Allow policy with context — passed to downstream Lambda
        return build_policy(
            principal_id=payload['sub'],
            effect='Allow',
            resource=event['methodArn'],
            context={
                'practice_id': practice_id,
                'role': payload['custom:role']
            }
        )

    except jwt.ExpiredSignatureError:
        raise Exception('Unauthorized')  # 401
    except Exception:
        raise Exception('Unauthorized')  # 401


def build_policy(principal_id, effect, resource, context):
    return {
        'principalId': principal_id,
        'policyDocument': {
            'Version': '2012-10-17',
            'Statement': [{'Action': 'execute-api:Invoke', 'Effect': effect, 'Resource': resource}]
        },
        'context': context
    }

Step 1: Browser sends preflight (before the real request)
  OPTIONS https://api.mybcat.com/appointments
  Origin: https://app.mybcat.com
  Access-Control-Request-Method: POST
  Access-Control-Request-Headers: Authorization, Content-Type

Step 2: API Gateway must respond with permission
  HTTP 200
  Access-Control-Allow-Origin: https://app.mybcat.com
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
  Access-Control-Allow-Headers: Authorization, Content-Type
  Access-Control-Max-Age: 3600

Step 3: Browser sends the real request
  POST https://api.mybcat.com/appointments
  (with JWT, with body — now allowed)

# HTTP API — CORS in Terraform (one block, handles everything)
cors_configuration {
  allow_origins = ["https://app.mybcat.com"]
  allow_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
  allow_headers = ["Authorization", "Content-Type", "X-Practice-Id"]
  max_age       = 3600
}

9am Monday — all 30 practices open simultaneously
Each practice has 10 agents booking appointments
Each agent clicks rapidly due to slow UI
= 300 agents × 10 clicks = 3,000 Lambda invocations/second

AWS Lambda account limit: 1,000 concurrent executions
Result: 2,000 requests per second get throttled
        Error responses flood practice UIs
        Agents book the same slot twice (race condition)
        Practice manager calls complaining

Block at the edge before traffic even reaches API Gateway:
  Rule: IP sends > 1,000 requests in 5 minutes → block for 1 hour
  Rule: Request body contains SQL injection pattern → block + log
  Rule: User-Agent is known bot/scraper → block
  Rule: Request origin is not US → block (MyBCAT serves US-only)

Cost: ~$5/month for WAF + $0.60/million requests evaluated
Benefit: Malicious traffic never consumes Lambda concurrency

Account-level:  10,000 requests/second (default, can be raised)
Stage-level:    500 requests/second per route
Usage plan:     Per-API-key quotas (REST API only)

If a single practice's integration goes into a loop:
  Their API key's quota is exhausted → 429 only for them
  All other practices are unaffected

Booking Lambda:          reserved = 200
Post-call workflow:      reserved = 100
Analytics/reporting:     reserved = 20
Background jobs:         reserved = 10
                         ─────────────
Total reserved:          330
Remaining for bursts:    670 (shared pool)

Booking Lambda always has 200 slots available regardless of
what other Lambdas are doing. Critical path is protected.

/v1/appointments → original Lambda (maintained for backward compat)
/v2/appointments → new Lambda (breaking change in response format)

Clients choose when to migrate. You support both until v1 is sunset.

API Gateway routing:
  GET /v1/* → appointment-handler-v1:stable alias
  GET /v2/* → appointment-handler-v2:stable alias

Deprecation process:
  1. Add response header: Deprecation: true, Sunset: 2026-10-01
  2. Log which API keys are still calling v1 (CloudWatch)
  3. Contact practices still on v1 before sunset date
  4. On sunset date: v1 returns 410 Gone with migration guide URL

API Gateway Stage: v1 → Lambda alias: v1 (points to version 3 of Lambda)
API Gateway Stage: v2 → Lambda alias: v2 (points to version 7 of Lambda)

Benefit: you can run different versions of the same Lambda
         behind different stages without duplicate code

Production: 100% traffic → Lambda:v5
Deploy v6:
  API Gateway canary: 10% → Lambda:v6, 90% → Lambda:v5
  Monitor error rate and latency for 30 minutes
  If healthy: promote v6 to 100%
  If errors spike: rollback by removing canary — zero downtime

External Client
      ↓
  Gateway  ← handles every request (runtime)
      ↓
Policy Engine ← inbound → backend → outbound → error policies
      ↓
  Backend  ← Azure Function, App Service, Logic App, any HTTP endpoint
      ↑
Developer Portal ← auto-generated docs, interactive testing for external devs
Management API   ← configure APIs, policies, products, subscriptions

<policies>
  <inbound>
    <validate-jwt header-name="Authorization" failed-validation-httpcode="401">
      <openid-config url="https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration"/>
    </validate-jwt>

    <!-- Rate limit by practice ID extracted from JWT — not by IP -->
    <rate-limit-by-key
      calls="1000"
      renewal-period="60"
      counter-key="@(context.Request.Headers.GetValueOrDefault("Authorization")
                     .AsJwt()?.Claims["practice_id"].FirstOrDefault())" />
  </inbound>
</policies>

<outbound>
  <!-- Backend returns full record — strip fields clients should not see -->
  <json-to-xml apply="always" consider-accept-header="false" />
  <xsl-transform>
    <xsl:stylesheet version="1.0">
      <xsl:template match="@internalNotes|@billingCode|@auditTrail" />
    </xsl:stylesheet>
  </xsl-transform>
</outbound>

<inbound>
  <retry condition="@(context.Response.StatusCode >= 500)"
         count="3"
         interval="2"
         delta="1"
         max-interval="10"
         first-fast-retry="true">
    <forward-request />
  </retry>
</inbound>

Features:
  Interactive API explorer — try any endpoint in the browser
  Auto-generated code samples (C#, Python, curl, JavaScript)
  API subscription management — developers self-serve API keys
  Changelog — track API version history
  Usage analytics per developer/subscription
  Sandbox environment — separate from production, safe to explore

Choose AWS HTTP API when:
  ✓ Simple Lambda proxy — internal APIs, mobile/web app backends
  ✓ Cognito JWT auth is sufficient
  ✓ Cost matters — $1/million requests
  ✓ Low latency matters — ~1ms overhead

Choose AWS REST API when:
  ✓ Per-client rate limits (usage plans + API keys)
  ✓ Response caching for stable data
  ✓ WAF integration for public APIs
  ✓ Request/response transformation (if VTL templates are acceptable)

Choose Azure API Management when:
  ✓ Complex policy logic (retry, circuit breaker, response transformation)
  ✓ External developer portal needed
  ✓ Multiple backends with routing rules
  ✓ Built-in API versioning and revision management
  ✓ Already heavily invested in Azure ecosystem

# API Gateway
resource "aws_apigatewayv2_api" "main" {
  name          = "mybcat-${var.env}"
  protocol_type = "HTTP"

  cors_configuration {
    allow_origins = var.env == "prod" ? ["https://app.mybcat.com"] : ["*"]
    allow_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allow_headers = ["Authorization", "Content-Type", "X-Idempotency-Key"]
    max_age       = 3600
  }
}

# Cognito JWT Authoriser
resource "aws_apigatewayv2_authorizer" "cognito" {
  api_id           = aws_apigatewayv2_api.main.id
  authorizer_type  = "JWT"
  identity_sources = ["$request.header.Authorization"]
  name             = "cognito"

  jwt_configuration {
    audience = [aws_cognito_user_pool_client.app.id]
    issuer   = "https://cognito-idp.${var.region}.amazonaws.com/${aws_cognito_user_pool.main.id}"
  }
}

# Stage with access logging
resource "aws_apigatewayv2_stage" "default" {
  api_id      = aws_apigatewayv2_api.main.id
  name        = "$default"
  auto_deploy = true

  access_log_settings {
    destination_arn = aws_cloudwatch_log_group.api_logs.arn
    format = jsonencode({
      requestId      = "$context.requestId"
      routeKey       = "$context.routeKey"
      status         = "$context.status"
      latency        = "$context.integrationLatency"
      practiceId     = "$context.authorizer.practice_id"
      userAgent      = "$context.identity.userAgent"
    })
  }
}

# Reusable module for Lambda routes
module "book_appointment_route" {
  source         = "./modules/api_route"
  api_id         = aws_apigatewayv2_api.main.id
  authorizer_id  = aws_apigatewayv2_authorizer.cognito.id
  route_key      = "POST /appointments"
  lambda_arn     = aws_lambda_function.book_appointment.invoke_arn
}

module "get_slots_route" {
  source         = "./modules/api_route"
  api_id         = aws_apigatewayv2_api.main.id
  authorizer_id  = aws_apigatewayv2_authorizer.cognito.id
  route_key      = "GET /practices/{practiceId}/slots"
  lambda_arn     = aws_lambda_function.get_slots.invoke_arn
}

# Health check — mock response, no Lambda invoked
resource "aws_apigatewayv2_route" "health" {
  api_id    = aws_apigatewayv2_api.main.id
  route_key = "GET /health"
  target    = "integrations/${aws_apigatewayv2_integration.health_mock.id}"
}

# BAD — stack trace reaches the client
def handler(event, context):
    patient = db.get_patient(event['patientId'])
    return patient  # KeyError if not found → full traceback in response

# GOOD — structured errors, internal details stay in CloudWatch
def handler(event, context):
    try:
        patient = db.get_patient(event['patientId'])
        if not patient:
            return {'statusCode': 404, 'body': json.dumps({'error': 'Not found'})}
        return {'statusCode': 200, 'body': json.dumps(patient)}
    except Exception:
        logger.exception("Unhandled error in get_patient")
        return {'statusCode': 500, 'body': json.dumps({'error': 'Internal server error'})}

# NEVER in production
allow_origins = ["*"]

# Always scope to your actual domain
allow_origins = ["https://app.mybcat.com"]

                    Users (browsers, mobile apps)
                              ↓
                    CloudFront (CDN + WAF)
                    ├── Static assets served from edge
                    ├── WAF: blocks bots, SQL injection, geo-restrictions
                    └── Forwards API requests to API Gateway
                              ↓
                    API Gateway (HTTP API)
                    ├── JWT Authoriser (Cognito)
                    ├── CORS headers on all routes
                    ├── Access logging → CloudWatch
                    └── Routes:
                        ├── POST /appointments → book-appt Lambda
                        ├── GET  /appointments/{id} → get-appt Lambda
                        ├── PUT  /appointments/{id}/cancel → cancel-appt Lambda
                        ├── GET  /practices/{id}/slots → get-slots Lambda
                        ├── POST /calls/webhook → call-event Lambda (no auth)
                        ├── GET  /health → mock response (200 OK)
                        └── WebSocket /realtime → ws-connect, ws-message, ws-disconnect Lambdas
                              ↓
                    Lambda Functions
                    ├── IAM roles with least privilege
                    ├── No PHI in CloudWatch logs (correlation IDs only)
                    ├── Secrets from Secrets Manager (not env vars)
                    └── DynamoDB + RDS + SQS backends