pos-system/docs/en/skills/api-gateway-advanced.md

name, description

name	description
api-gateway-advanced	Advanced API Gateway patterns for GoodGo microservices including API composition, request/response transformation, service mesh integration, advanced routing, and gateway-level resilience.

API Gateway Advanced Patterns

When to Use This Skill

Use this skill when:

• Implementing API composition and aggregation
• Transforming requests/responses at gateway level
• Integrating service mesh with Traefik
• Implementing advanced routing strategies
• Adding gateway-level circuit breakers
• Implementing API versioning at gateway

API Gateway Architecture

The API Gateway serves as the single entry point for all client requests, handling routing, composition, transformation, and resilience patterns.

graph TB
    Client[Client Application] --> Gateway[API Gateway]
    
    subgraph Gateway["API Gateway Components"]
        Router[Request Router]
        Auth[Authentication/Authorization]
        RateLimit[Rate Limiting]
        CircuitBreaker[Circuit Breaker]
        Cache[Gateway Cache]
        Transformer[Request/Response Transformer]
        Composition[API Composition Engine]
    end
    
    Gateway --> Router
    Router --> Auth
    Auth --> RateLimit
    RateLimit --> CircuitBreaker
    CircuitBreaker --> Cache
    Cache --> Transformer
    Transformer --> Composition
    
    Composition --> Service1[User Service]
    Composition --> Service2[Order Service]
    Composition --> Service3[Payment Service]
    Composition --> Service4[Other Services]
    
    CircuitBreaker -.-> Service1
    CircuitBreaker -.-> Service2
    CircuitBreaker -.-> Service3
    CircuitBreaker -.-> Service4
    
    Cache --> Redis[(Redis Cache)]
    
    style Gateway fill:#e1f5ff
    style Composition fill:#fff4e1
    style CircuitBreaker fill:#ffe1e1

Request Routing Flow

Requests flow through the gateway middleware chain in a specific order, ensuring proper handling at each stage.

sequenceDiagram
    participant Client
    participant Gateway
    participant RateLimit
    participant Auth
    participant CircuitBreaker
    participant Cache
    participant Transformer
    participant Service
    
    Client->>Gateway: HTTP Request
    Gateway->>RateLimit: Check Rate Limit
    RateLimit-->>Gateway: Allowed
    
    Gateway->>Auth: Validate Token
    Auth-->>Gateway: Authenticated
    
    Gateway->>CircuitBreaker: Check Circuit State
    alt Circuit Open
        CircuitBreaker-->>Gateway: Service Unavailable
        Gateway-->>Client: 503 Error
    else Circuit Closed/Half-Open
        Gateway->>Cache: Check Cache
        alt Cache Hit
            Cache-->>Gateway: Cached Response
            Gateway->>Transformer: Transform Response
            Transformer-->>Gateway: Transformed
            Gateway-->>Client: Response
        else Cache Miss
            Gateway->>Transformer: Transform Request
            Transformer-->>Gateway: Transformed
            Gateway->>Service: Forward Request
            Service-->>Gateway: Response
            Gateway->>Cache: Store in Cache
            Gateway->>Transformer: Transform Response
            Transformer-->>Gateway: Transformed
            Gateway-->>Client: Response
        end
    end

API Composition Patterns

API composition enables the gateway to aggregate data from multiple services, reducing client round trips and improving performance.

Fan-Out / Fan-In Pattern (Parallel Aggregation)

graph LR
    Client[Client Request] --> Gateway[API Gateway]
    
    subgraph Gateway["API Composition"]
        Comp[Composition Handler]
    end
    
    Gateway --> Comp
    
    Comp -->|Parallel Calls| S1[User Service]
    Comp -->|Parallel Calls| S2[Order Service]
    Comp -->|Parallel Calls| S3[Payment Service]
    
    S1 -->|Response| Comp
    S2 -->|Response| Comp
    S3 -->|Response| Comp
    
    Comp -->|Aggregated Response| Client
    
    style Comp fill:#fff4e1
    style S1 fill:#e1ffe1
    style S2 fill:#e1ffe1
    style S3 fill:#e1ffe1

Chaining Pattern (Sequential Calls with Compensation)

sequenceDiagram
    participant Client
    participant Gateway
    participant OrderService
    participant PaymentService
    
    Client->>Gateway: Create Order Request
    Gateway->>OrderService: POST /orders
    OrderService-->>Gateway: Order Created
    
    Gateway->>PaymentService: POST /payments
    alt Payment Success
        PaymentService-->>Gateway: Payment Processed
        Gateway-->>Client: Success Response
    else Payment Failed
        PaymentService-->>Gateway: Payment Error
        Gateway->>OrderService: DELETE /orders/:id (Compensate)
        OrderService-->>Gateway: Order Deleted
        Gateway-->>Client: Error Response
    end

Key Patterns

API Composition

// Aggregate multiple service responses
const [user, orders, payments] = await Promise.all([
  userClient.get(`/users/${userId}`),
  orderClient.get(`/orders?userId=${userId}`),
  paymentClient.get(`/payments?userId=${userId}`),
]);

Request/Response Transformation

// Transform at gateway level
transformer.addRule({
  path: '/api/v1/users',
  requestTransform: (req) => {
    if (!req.query.page) req.query.page = '1';
    return req;
  },
  responseTransform: (res, data) => {
    return { success: true, data };
  },
});

Best Practices

1. Use API composition for aggregating related data
2. Cache at gateway for frequently accessed data
3. Implement circuit breaker at gateway level
4. Keep transformations simple and testable

Resources

• Traefik Documentation
• Middleware Patterns
• Skill Source: .cursor/skills/api-gateway-advanced/SKILL.md