Api Gateway Patterns

API Gateway Patterns

When to Use

• Designing an API gateway for microservices
• Implementing rate limiting, authentication, or request routing
• Evaluating BFF (Backend for Frontend) pattern
• Adding circuit breaking to external service calls

Gateway Architecture

                    ┌─────────────────────┐
                    │    API Gateway       │
                    │                     │
  Clients ────────►│  1. Rate Limiting    │
                    │  2. Authentication   │
                    │  3. Request Routing  │
                    │  4. Load Balancing   │
                    │  5. Circuit Breaking │
                    │  6. Response Caching │
                    │  7. Logging/Tracing  │
                    └────┬────┬────┬──────┘
                         │    │    │
                    ┌────┘    │    └────┐
                    ▼         ▼         ▼
              ┌──────┐  ┌──────┐  ┌──────┐
              │Svc A │  │Svc B │  │Svc C │
              └──────┘  └──────┘  └──────┘

Rate Limiting Patterns

Token Bucket (recommended)

// Allows burst then throttles
const rateLimiter = {
  bucketSize: 100,      // Max tokens
  refillRate: 10,       // Tokens per second
  refillInterval: 1000, // ms
};
// Burst: 100 requests instantly, then 10/sec sustained

Sliding Window

// More accurate, no burst
// Count requests in last N seconds
// Redis implementation:
// ZADD rate:{userId} {timestamp} {requestId}
// ZREMRANGEBYSCORE rate:{userId} 0 {timestamp - window}
// ZCARD rate:{userId}

Rate Limit by Tier

| Tier | Rate Limit | Burst | |------|-----------|-------| | Free | 100 req/hour | 10 req/sec | | Basic | 1000 req/hour | 50 req/sec | | Pro | 10000 req/hour | 200 req/sec | | Enterprise | Custom | Custom |

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1619472000
Retry-After: 60

API Versioning Strategies

| Strategy | Example | Pros | Cons | |----------|---------|------|------| | URL path | /v1/users | Simple, clear | URL pollution | | Header | Accept: application/vnd.api.v1+json | Clean URLs | Hidden, harder to test | | Query param | /users?version=1 | Easy to switch | Messy |

Recommendation: URL path for public APIs, header for internal APIs.

Deprecation Policy

v1: Active → Deprecated → Sunset
    │          │           │
    └──────────┘           │
      6 months minimum     │
      communication        │
                           └── Remove with 3-month warning

BFF (Backend for Frontend)

┌────────┐     ┌─────────────┐     ┌──────────┐
│ Mobile  │────►│ Mobile BFF  │────►│          │
│ App     │     │ (optimized) │     │          │
└────────┘     └─────────────┘     │  Core    │
                                    │  Services │
┌────────┐     ┌─────────────┐     │          │
│ Web    │────►│  Web BFF    │────►│          │
│ App     │     │ (full data) │     │          │
└────────┘     └─────────────┘     └──────────┘

Mobile BFF: Less data, compressed images, offline-first
Web BFF:    Full data, SSR support, WebSocket

Circuit Breaker

enum CircuitState { CLOSED, OPEN, HALF_OPEN }

class CircuitBreaker {
  private state = CircuitState.CLOSED;
  private failureCount = 0;
  private successCount = 0;
  private lastFailureTime: Date;

  private readonly threshold = 5;        // Failures to open
  private readonly timeout = 30000;      // ms before half-open
  private readonly halfOpenMax = 3;      // Successes to close

  async execute(fn: () => Promise): Promise {
    if (this.state === CircuitState.OPEN) {
      if (Date.now() - this.lastFailureTime.getTime() > this.timeout) {
        this.state = CircuitState.HALF_OPEN;
      } else {
        throw new Error('Circuit is OPEN — service unavailable');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    if (this.state === CircuitState.HALF_OPEN) {
      this.successCount++;
      if (this.successCount >= this.halfOpenMax) {
        this.state = CircuitState.CLOSED;
        this.failureCount = 0;
      }
    }
    this.failureCount = 0;
  }

  private onFailure() {
    this.failureCount++;
    this.lastFailureTime = new Date();
    if (this.failureCount >= this.threshold) {
      this.state = CircuitState.OPEN;
    }
  }
}

Request/Response Transformation

// Gateway aggregation — single client call, multiple services
@Get('dashboard')
async getDashboard(@User() user) {
  const [profile, stats, notifications] = await Promise.allSettled([
    this.userService.getProfile(user.id),
    this.billingService.getStats(user.companyId),
    this.notificationService.getUnread(user.id),
  ]);

  return {
    profile: profile.status === 'fulfilled' ? profile.value : null,
    stats: stats.status === 'fulfilled' ? stats.value : null,
    notifications: notifications.status === 'fulfilled' ? notifications.value : [],
  };
  // Graceful degradation: partial response even if one service fails
}

Quality Gates

• [ ] Rate limiting configured on all public endpoints
• [ ] Authentication at gateway level (not duplicated in services)
• [ ] API versioning strategy defined and documented
• [ ] Circuit breakers on all external service calls
• [ ] Request/response logging with correlation IDs
• [ ] Health check endpoint for each downstream service
• [ ] Timeout configured for all downstream calls

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: camilooscargbaptista
• Source: camilooscargbaptista/cto-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.