goplt/docs/content/adr/0032-api-gateway-strategy.md

ADR-0032: API Gateway Strategy

Status

Accepted

Context

The platform follows a microservices architecture where each service is independently deployable. We need a central entry point that handles:

• Request routing to backend services
• Authentication and authorization at the edge
• Rate limiting and throttling
• CORS and request/response transformation
• Service discovery integration

Options considered:

1. Custom API Gateway - Build our own gateway service
2. Kong - Open-source API Gateway
3. Envoy - High-performance proxy
4. Traefik - Modern reverse proxy

Decision

Implement a custom API Gateway service as a core infrastructure component in Epic 1:

1. API Gateway as Core Component:

   • Entry point: cmd/api-gateway/
   • Implementation: services/gateway/internal/
   • Implemented in Epic 1 (not deferred to Epic 8)
   • Required for microservices architecture, not optional

2. Responsibilities:

   • Request Routing: Route requests to backend services via service discovery
   • Authentication: Validate JWT tokens via Auth Service
   • Authorization: Check permissions via Authz Service (for route-level auth)
   • Rate Limiting: Per-user and per-IP rate limiting
   • CORS: Handle cross-origin requests
   • Request Transformation: Modify requests before forwarding
   • Response Transformation: Modify responses before returning
   • Load Balancing: Distribute requests across service instances

3. Integration Points:

   • Service registry for service discovery
   • Auth Service client for token validation
   • Authz Service client for permission checks
   • Cache (Redis) for rate limiting state

4. Implementation Approach:

   • Built with Go (Gin/Echo framework)
   • Uses service clients for backend communication
   • Configurable routing rules
   • Middleware-based architecture

Architecture

graph TB
    Client[Client] --> Gateway[API Gateway<br/>:8080]
    
    Gateway --> AuthClient[Auth Service Client]
    Gateway --> AuthzClient[Authz Service Client]
    Gateway --> ServiceRegistry[Service Registry]
    Gateway --> Cache[Cache<br/>Rate Limiting]
    
    AuthClient --> AuthSvc[Auth Service<br/>:8081]
    AuthzClient --> AuthzSvc[Authz Service<br/>:8083]
    ServiceRegistry --> BackendSvc[Backend Services]
    
    Gateway --> BackendSvc
    
    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
    style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
    style BackendSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff

Request Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant AuthSvc
    participant AuthzSvc
    participant Registry
    participant BackendSvc
    
    Client->>Gateway: HTTP Request
    Gateway->>Gateway: Rate limiting check
    Gateway->>AuthSvc: Validate JWT (gRPC)
    AuthSvc-->>Gateway: Token valid + user info
    Gateway->>AuthzSvc: Check route permission (gRPC, optional)
    AuthzSvc-->>Gateway: Authorized
    Gateway->>Registry: Discover backend service
    Registry-->>Gateway: Service endpoint
    Gateway->>BackendSvc: Forward request (gRPC/HTTP)
    BackendSvc-->>Gateway: Response
    Gateway-->>Client: HTTP Response

Consequences

Positive

• Single Entry Point: All external traffic goes through one gateway
• Centralized Security: Authentication and authorization at the edge
• Performance: Rate limiting and caching at gateway level
• Flexibility: Easy to add new routes and services
• Consistency: Uniform API interface for clients
• Observability: Central point for metrics and logging

Negative

• Single Point of Failure: Gateway failure affects all traffic
• Additional Latency: Extra hop in request path
• Complexity: Additional service to maintain and deploy
• Scaling: Gateway must scale to handle all traffic

Mitigations

1. High Availability: Deploy multiple gateway instances behind load balancer
2. Circuit Breakers: Implement circuit breakers for backend service failures
3. Caching: Cache authentication results and service endpoints
4. Monitoring: Comprehensive monitoring and alerting
5. Graceful Degradation: Fallback mechanisms for service failures

Implementation Strategy

Epic 1: Core Infrastructure

• Create cmd/api-gateway/ entry point
• Implement basic routing with service discovery
• JWT validation via Auth Service client
• Rate limiting middleware
• CORS support

Epic 2-3: Enhanced Features

• Permission-based routing (via Authz Service)
• Request/response transformation
• Advanced load balancing
• Health check integration

Configuration

gateway:
  port: 8080
  routes:
    - path: /api/v1/auth/**
      service: auth-service
      auth_required: false
    - path: /api/v1/users/**
      service: identity-service
      auth_required: true
      permission: user.read
    - path: /api/v1/blog/**
      service: blog-service
      auth_required: true
      permission: blog.post.read
  rate_limiting:
    enabled: true
    per_user: 100/minute
    per_ip: 1000/minute
  cors:
    allowed_origins: ["*"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE"]

References

• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy
• ADR-0031: Service Repository Structure
• API Gateway Pattern