toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f2a14f2c5b18516085da2b3747c399952cb969e
goplt/docs/content/adr/0032-api-gateway-strategy.md
0x1d b4b918cba8
All checks were successful
CI / Test (pull_request) Successful in 27s
Details
CI / Lint (pull_request) Successful in 20s
Details
CI / Build (pull_request) Successful in 16s
Details
CI / Format Check (pull_request) Successful in 2s
Details
docs: ensure newline before lists across docs for MkDocs rendering
2025-11-06 10:56:50 +01:00

5.5 KiB
Raw Blame History

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