API Gateway

// API Gateway cross-cutting concerns:
//
// Client Request ──▶ API Gateway ──▶ Backend Service
//
// What the gateway handles:
// ┌──────────────────────────────────────────────────────────┐
// │ 1. SSL Termination     — decrypt HTTPS, forward HTTP     │
// │ 2. Authentication      — validate JWT / API key / OAuth  │
// │ 3. Authorisation       — check scopes / roles            │
// │ 4. Rate Limiting       — 100 req/min per API key         │
// │ 5. Request Routing     — /api/courses → course-service   │
// │                          /api/users   → user-service     │
// │ 6. Protocol Translation— REST → gRPC (grpc-gateway)      │
// │ 7. Request Transform   — add headers, rewrite paths      │
// │ 8. Response Aggregation— fan out to N services, merge    │
// │ 9. Caching             — cache GET responses at edge     │
// │ 10. Observability      — unified access logs, metrics    │
// └──────────────────────────────────────────────────────────┘

// Kong JWT plugin (declarative config):
plugins:
  - name: jwt
    config:
      key_claim_name: kid
      claims_to_verify: [exp, nbf]
      maximum_expiration: 3600

// After validation, Kong forwards to backend:
// X-Consumer-ID: uuid
// X-Consumer-Username: user@aicancode.org
// X-Consumer-Custom-ID: 12345

// AWS API Gateway — JWT authorizer (Terraform):
resource "aws_api_gateway_authorizer" "jwt" {
  name                   = "jwt-authorizer"
  rest_api_id            = aws_api_gateway_rest_api.main.id
  authorizer_uri         = aws_lambda_function.jwt_validator.invoke_arn
  authorizer_result_ttl_in_seconds = 300   // cache auth result for 5min
  type                   = "TOKEN"
  identity_source        = "method.request.header.Authorization"
}

// Backend (Spring Boot) — trusts forwarded identity, no JWT parsing needed:
@GetMapping("/profile")
public ResponseEntity<User> getProfile(
    @RequestHeader("X-User-ID") String userId) {   // set by gateway
  return ResponseEntity.ok(userService.findById(userId));
}

// Kong rate limiting plugin:
plugins:
  - name: rate-limiting
    config:
      minute: 100          // 100 req/min per consumer
      hour: 5000
      policy: redis        // shared across gateway instances
      redis_host: redis.internal
      redis_port: 6379
      error_code: 429
      error_message: "Rate limit exceeded. Retry after 60 seconds."

// AWS API Gateway usage plan:
resource "aws_api_gateway_usage_plan" "free_tier" {
  name = "free-tier"
  throttle_settings {
    burst_limit = 50     // max concurrent request burst
    rate_limit  = 10     // steady-state req/sec
  }
  quota_settings {
    limit  = 1000        // 1000 req/month
    period = "MONTH"
  }
}

// Rate limit headers returned to client:
// X-RateLimit-Limit: 100
// X-RateLimit-Remaining: 87
// X-RateLimit-Reset: 1744567200

// Traffic flow with both gateway and mesh:
//
//              Internet
//                 │
//         [API Gateway]        ← North-South: auth, rate limit, routing
//           /        \
//    [Service A]  [Service B]
//       │    \       │
//      [sidecar] [sidecar]     ← East-West: Istio/Linkerd sidecars
//                              ← handles: mTLS, retries, circuit breaking,
//                              ←          distributed tracing, traffic shifting
//
// API Gateway concerns:     Service Mesh concerns:
// ✓ External auth (JWT)     ✓ Internal mTLS (service identity)
// ✓ Rate limiting           ✓ Retries + timeouts
// ✓ SSL termination         ✓ Circuit breaking
// ✓ Public API versioning   ✓ Load balancing (L7)
// ✓ Client-facing docs      ✓ Distributed tracing (Jaeger)