API Gateway Builder

GATEWAY              TYPE            BEST FOR                   COST MODEL
---------------------------------------------------------------------------
AWS API GW (HTTP)    Managed         Serverless, low complexity $1/million reqs
AWS API GW (REST)    Managed         WebSocket, caching, WAF    $3.50/million
Kong                 Self-managed    Multi-cloud, plugins, K8s  Open source/EE
Envoy / Istio        Self-managed    Service mesh, gRPC         Free (infra cost)
Traefik              Self-managed    Docker/K8s auto-discovery  Open source/EE
NGINX                Self-managed    Max performance, mature    Open source/Plus

CHOOSE AWS API GW:  Serverless backend, AWS-native, <10K req/s
CHOOSE KONG:        Multi-cloud, complex plugins, Kubernetes-native
CHOOSE ENVOY:       Service mesh, gRPC-native, fine-grained traffic control
CHOOSE NGINX:       Maximum raw performance, simple routing needs

_format_version: "3.0"

services:
  - name: user-service
    url: [reference URL]
    connect_timeout: 5000
    read_timeout: 30000
    retries: 3
    routes:
      - name: user-routes
        paths: [/api/v1/users]
        methods: [GET, POST, PUT, DELETE]
        strip_path: false
        protocols: [https]

plugins:
  - name: rate-limiting
    config:
      minute: 100
      hour: 5000
      policy: redis
      redis_host: redis
      fault_tolerant: true        # Fail open if Redis down

  - name: correlation-id
    config:
      header_name: X-Request-ID
      generator: uuid
      echo_downstream: true

  - name: request-size-limiting
    config:
      allowed_payload_size: 10    # MB

plugins:
  - name: rate-limiting
    route: login-route
    config:
      minute: 10                  # Strict limit on login attempts

  - name: jwt
    service: user-service
    config:
      claims_to_verify: [exp]
      header_names: [Authorization]

  - name: request-transformer
    service: user-service
    config:
      add:
        headers: ["X-Gateway-Version:1.0"]
      remove:
        headers: [Cookie]

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limit-api
plugin: rate-limiting
config:
  minute: 100
  policy: local
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user-api
  annotations:
    konghq.com/plugins: rate-limit-api,jwt-auth
spec:
  ingressClassName: kong
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api/v1/users
            pathType: Prefix
            backend:
              service: { name: user-service, port: { number: 8080 } }

Resources:
  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: prod
      CorsConfiguration:
        AllowOrigins: ["[reference URL]"]
        AllowMethods: [GET, POST, PUT, DELETE]
        AllowHeaders: [Authorization, Content-Type]
      Auth:
        DefaultAuthorizer: JWTAuthorizer
        Authorizers:
          JWTAuthorizer:
            IdentitySource: $request.header.Authorization
            JwtConfiguration:
              issuer: [reference URL]
              audience: [api.example.com]
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
        ThrottlingRateLimit: 100

  UsagePlan:
    Type: AWS::ApiGateway::UsagePlan
    Properties:
      Throttle:
        BurstLimit: 200
        RateLimit: 100
      Quota:
        Limit: 100000
        Period: MONTH

ALGORITHM           HOW IT WORKS                    TRADE-OFF
---------------------------------------------------------------------------
Fixed Window        Count per time window            Simple; burst at edges
Sliding Window      Weighted current + previous      Good accuracy/memory
Token Bucket        Tokens refill at steady rate     Allows controlled bursts
Leaky Bucket        Process at fixed rate, queue     Smooth; no bursts

TIER        KEY              LIMIT           PURPOSE
--------------------------------------------------------------
Global      -                10,000 req/s    Protect infrastructure
Per-IP      client IP        100 req/min     Prevent abuse
Per-User    auth token/key   1,000 req/hr    Fair usage
Per-Route   path + method    50 req/min      Protect heavy endpoints

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

Client -> Gateway -> [Auth Plugin] -> Backend Service
                         |
                    Validate token
                    Extract claims
                    Inject headers:
                      X-User-ID, X-User-Role, X-Tenant-ID
                         |
                    Strip Authorization header
                    (backend trusts gateway headers)

plugins:
  - name: key-auth
    service: api-service
    config:
      key_names: [X-API-Key, apikey]
      key_in_header: true
      key_in_query: true
      hide_credentials: true      # Remove key before proxying

# Add security headers to all responses
plugins:
  - name: response-transformer
    config:
      add:
        headers:
          - "Strict-Transport-Security:max-age=31536000; includeSubDomains"
          - "X-Content-Type-Options:nosniff"
          - "X-Frame-Options:DENY"
      remove:
        headers: [Server, X-Powered-By]

PATH-BASED:
  /api/v1/users/*     -> user-service:8080
  /api/v1/orders/*    -> order-service:8080
  /api/v2/users/*     -> user-service-v2:8080

HEADER-BASED (e.g., mobile vs web):
  X-Client-Type: mobile  -> user-service-mobile
  X-Client-Type: web     -> user-service-web

CANARY RELEASES:
  10% traffic -> canary backend
  90% traffic -> stable backend
  Sticky routing per consumer for consistency

plugins:
  - name: proxy-cache
    config:
      strategy: redis
      content_type: [application/json]
      request_method: [GET, HEAD]
      response_code: [200, 301]
      cache_ttl: 300
      vary_headers: [Authorization, Accept-Encoding]
      cache_control: true         # Respect Cache-Control headers

upstreams:
  - name: user-service
    healthchecks:
      active:
        http_path: /health
        healthy: { interval: 5, successes: 3 }
        unhealthy: { interval: 5, http_failures: 3, timeouts: 3 }
      passive:
        healthy: { successes: 5 }
        unhealthy: { http_failures: 5, timeouts: 3 }
    targets:
      - { target: "user-service-1:8080", weight: 100 }
      - { target: "user-service-2:8080", weight: 100 }

METRIC                      ALERT CONDITION
------------------------------------------------------
Request rate                Sudden spike or drop
Error rate (5xx)            > 1% sustained
Latency (p99)               > 2s
Rate limit hits             Sustained high rate
Auth failures               Spike (possible attack)
Upstream health             Any backend unhealthy
Cache hit ratio             < 50%

ROUTING:
  [ ] All routes use HTTPS
  [ ] API versioning implemented
  [ ] Health check endpoints excluded from auth

SECURITY:
  [ ] Auth enforced on all non-public routes
  [ ] Rate limiting (global, per-user, per-route)
  [ ] Request size limits set
  [ ] Security headers on all responses
  [ ] CORS with explicit allowed origins
  [ ] Sensitive headers stripped before proxying

RELIABILITY:
  [ ] Upstream health checks (active + passive)
  [ ] Timeouts on all upstream connections
  [ ] Circuit breaker for failing backends
  [ ] Graceful degradation documented

OBSERVABILITY:
  [ ] Access logging (structured JSON)
  [ ] Metrics exported (Prometheus/CloudWatch)
  [ ] Distributed tracing propagated
  [ ] Alerting on error rate, latency, rate limits

# Api Gateway Builder Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]