API Gateway Explained: Components, Patterns and Real-World Design

# Example: AWS API Gateway / Kong-style declarative configuration
# This shows how a gateway maps external routes to internal services

gateway:
  name: ecommerce-gateway
  base_url: https://api.shopexample.com

routes:
  # Route 1: Public product catalog — no auth required
  - path: /products
    method: GET
    upstream_service: http://product-service:8001/api/products
    auth_required: false          # Public endpoint, anyone can browse
    rate_limit:
      requests_per_minute: 300    # Still throttled to prevent scraping

  # Route 2: Place an order — must be authenticated
  - path: /orders
    method: POST
    upstream_service: http://order-service:8002/api/orders
    auth_required: true           # Gateway checks JWT before forwarding
    rate_limit:
      requests_per_minute: 30     # Stricter limit on write operations
    timeout_ms: 5000              # Gateway cancels request after 5s

  # Route 3: User profile — auth + request transformation
  - path: /users/{userId}/profile
    method: GET
    upstream_service: http://user-service:8003/api/profile
    auth_required: true
    transform_request:
      add_header:
        X-Internal-Request-Id: "${generate_uuid}"   # Gateway injects trace ID
        X-Caller-Service: "api-gateway"              # Downstream knows origin
    rate_limit:
      requests_per_minute: 60

// Simulating the middleware pipeline of an API Gateway in Node.js
// This shows HOW each component processes a request in sequence
// Real gateways (Kong, AWS API GW, Nginx) do this in compiled code,
// but the pipeline logic is identical.

const express = require('express');
const { v4: uuidv4 } = require('uuid');
const app = express();

app.use(express.json());

// ─── COMPONENT 1: Request Logger ────────────────────────────────────────────
// Every request gets a unique trace ID the moment it arrives
app.use((req, res, next) => {
  req.traceId = uuidv4();                         // Unique ID for distributed tracing
  req.arrivalTime = Date.now();
  console.log(`[GATEWAY] Incoming: ${req.method} ${req.path} | traceId=${req.traceId}`);
  next();
});

// ─── COMPONENT 2: Authentication Layer ──────────────────────────────────────
// Validate the token ONCE here — downstream services don't need to
const PUBLIC_ROUTES = ['/products'];              // Routes that skip auth

function authMiddleware(req, res, next) {
  if (PUBLIC_ROUTES.includes(req.path)) {
    return next();                                // Skip auth for public routes
  }

  const authHeader = req.headers['authorization'];
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({
      error: 'Authentication required',
      traceId: req.traceId                        // Always return traceId for debugging
    });
  }

  const token = authHeader.split(' ')[1];
  // In production: verify JWT signature, check expiry, decode claims
  // For demo: we accept any token that starts with 'valid-'
  if (!token.startsWith('valid-')) {
    return res.status(401).json({ error: 'Invalid token', traceId: req.traceId });
  }

  req.authenticatedUserId = token.replace('valid-', '');  // Extracted from JWT claims
  res.setHeader('X-Auth-User', req.authenticatedUserId);  // Pass identity downstream
  next();
}

app.use(authMiddleware);

// ─── COMPONENT 3: Rate Limiter ───────────────────────────────────────────────
// Simple in-memory rate limiter (production: use Redis for distributed state)
const requestCounts = {};                         // ip -> { count, windowStart }
const RATE_LIMIT = 5;                             // Max 5 requests per window
const WINDOW_MS  = 60 * 1000;                     // 60-second window

function rateLimiter(req, res, next) {
  const clientIp = req.ip;
  const now = Date.now();

  if (!requestCounts[clientIp] || now - requestCounts[clientIp].windowStart > WINDOW_MS) {
    requestCounts[clientIp] = { count: 1, windowStart: now };  // Reset window
    return next();
  }

  requestCounts[clientIp].count++;

  if (requestCounts[clientIp].count > RATE_LIMIT) {
    const retryAfter = Math.ceil((WINDOW_MS - (now - requestCounts[clientIp].windowStart)) / 1000);
    res.setHeader('Retry-After', retryAfter);     // Tell client when to retry
    return res.status(429).json({
      error: 'Rate limit exceeded',
      retryAfterSeconds: retryAfter,
      traceId: req.traceId
    });
  }

  next();
}

app.use(rateLimiter);

// ─── COMPONENT 4: Router + Load Balancer ────────────────────────────────────
// Round-robin across multiple instances of a service
const productServiceInstances = [
  'http://product-service-1:8001',
  'http://product-service-2:8001',
  'http://product-service-3:8001'
];
let roundRobinIndex = 0;

function getNextProductInstance() {
  const instance = productServiceInstances[roundRobinIndex];
  roundRobinIndex = (roundRobinIndex + 1) % productServiceInstances.length;  // Wrap around
  return instance;
}

// Public product route — no auth needed
app.get('/products', (req, res) => {
  const targetInstance = getNextProductInstance();
  console.log(`[GATEWAY] Routing GET /products -> ${targetInstance} | traceId=${req.traceId}`);

  // In production: forward the actual HTTP request using axios/node-fetch
  // For demo: simulate the downstream response
  res.json({
    _meta: { routedTo: targetInstance, traceId: req.traceId },
    products: [{ id: 1, name: 'Wireless Headphones', price: 79.99 }]
  });
});

// Protected order route
app.post('/orders', (req, res) => {
  console.log(`[GATEWAY] Routing POST /orders for user=${req.authenticatedUserId} | traceId=${req.traceId}`);

  // ─── COMPONENT 5: Request Transformer ─────────────────────────────────────
  // Strip the raw Authorization header — order-service trusts X-Auth-User instead
  const internalPayload = {
    ...req.body,
    requestedByUserId: req.authenticatedUserId,   // Inject verified identity
    gatewayTraceId: req.traceId                   // Inject trace ID for observability
    // Note: we do NOT forward req.headers.authorization to internal services
  };

  console.log('[GATEWAY] Transformed payload for order-service:', internalPayload);

  res.status(201).json({
    message: 'Order created',
    orderId: `ORD-${Date.now()}`,
    traceId: req.traceId
  });
});

app.listen(3000, () => {
  console.log('[GATEWAY] API Gateway running on port 3000');
});

// Demonstrates two advanced gateway patterns:
// 1. Response Aggregation (fan-out to multiple services, merge results)
// 2. Circuit Breaker (fail fast instead of cascading timeouts)

// ─── Circuit Breaker State Machine ──────────────────────────────────────────
// States: CLOSED (normal) -> OPEN (failing) -> HALF_OPEN (testing recovery)
const CircuitState = { CLOSED: 'CLOSED', OPEN: 'OPEN', HALF_OPEN: 'HALF_OPEN' };

class CircuitBreaker {
  constructor(serviceName, failureThreshold = 3, recoveryTimeoutMs = 10000) {
    this.serviceName       = serviceName;
    this.failureThreshold  = failureThreshold;  // Open circuit after 3 failures
    this.recoveryTimeout   = recoveryTimeoutMs; // Try again after 10 seconds
    this.state             = CircuitState.CLOSED;
    this.failureCount      = 0;
    this.lastFailureTime   = null;
  }

  async call(serviceCallFn) {
    // If circuit is OPEN, check if recovery timeout has passed
    if (this.state === CircuitState.OPEN) {
      const timeSinceFailure = Date.now() - this.lastFailureTime;
      if (timeSinceFailure < this.recoveryTimeout) {
        // Still in open state — fail fast without calling the service
        console.log(`[CIRCUIT] ${this.serviceName} is OPEN — fast failing`);
        throw new Error(`${this.serviceName} circuit is open — service unavailable`);
      }
      // Timeout elapsed — try one probe request
      console.log(`[CIRCUIT] ${this.serviceName} moving to HALF_OPEN — sending probe`);
      this.state = CircuitState.HALF_OPEN;
    }

    try {
      const result = await serviceCallFn();      // Attempt the actual service call
      this.onSuccess();                          // Reset on success
      return result;
    } catch (error) {
      this.onFailure();                          // Track failure
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = CircuitState.CLOSED;            // Restore normal operation
    console.log(`[CIRCUIT] ${this.serviceName} — circuit CLOSED (healthy)`);
  }

  onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    if (this.failureCount >= this.failureThreshold || this.state === CircuitState.HALF_OPEN) {
      this.state = CircuitState.OPEN;            // Trip the circuit
      console.log(`[CIRCUIT] ${this.serviceName} — circuit OPENED after ${this.failureCount} failures`);
    }
  }
}

// ─── Simulated Downstream Services ──────────────────────────────────────────
let inventoryCallCount = 0;

async function fetchUserProfile(userId) {
  // Simulates user-service responding successfully
  return { userId, name: 'Amara Osei', tier: 'Gold' };
}

async function fetchRecentOrders(userId) {
  // Simulates order-service responding successfully
  return { userId, orders: [{ orderId: 'ORD-001', total: 149.99, status: 'Shipped' }] };
}

async function fetchInventoryStatus(productId) {
  // Simulates a flaky inventory service that fails intermittently
  inventoryCallCount++;
  if (inventoryCallCount <= 3) {                 // First 3 calls fail
    throw new Error('inventory-service: connection refused');
  }
  return { productId, inStock: true, quantity: 47 };
}

// ─── Circuit Breakers (one per downstream service) ───────────────────────────
const inventoryCircuit = new CircuitBreaker('inventory-service', 3, 5000);

// ─── Gateway Aggregation Handler ────────────────────────────────────────────
// Client makes ONE call to /dashboard — gateway fans out to 3 services
async function handleDashboardRequest(userId, productId) {
  console.log(`\n[GATEWAY] Dashboard request for userId=${userId}, productId=${productId}`);

  // Fan out: run user profile and orders in PARALLEL (faster than serial)
  const [userProfile, recentOrders] = await Promise.all([
    fetchUserProfile(userId),
    fetchRecentOrders(userId)
  ]);

  // Inventory goes through circuit breaker — it's a non-critical enhancement
  let inventoryData = null;
  try {
    inventoryData = await inventoryCircuit.call(() => fetchInventoryStatus(productId));
  } catch (circuitError) {
    // GRACEFUL DEGRADATION: dashboard still works without inventory data
    console.log(`[GATEWAY] Inventory unavailable — degraded response: ${circuitError.message}`);
    inventoryData = { productId, inStock: null, message: 'Inventory temporarily unavailable' };
  }

  // Aggregate all responses into one payload for the client
  return {
    user:      userProfile,
    orders:    recentOrders,
    inventory: inventoryData
  };
}

// ─── Simulate 5 consecutive dashboard requests ──────────────────────────────
(async () => {
  for (let requestNum = 1; requestNum <= 5; requestNum++) {
    const response = await handleDashboardRequest('user-99', 'product-headphones');
    console.log(`[GATEWAY] Response aggregated:`, JSON.stringify(response.inventory));
  }
})();