🚪 API Gateway Implementation

What Is an API Gateway?

An API Gateway is a single entry point that sits between clients and your backend services. Every request comes in through the gateway, which decides where it goes, applies shared policies, and can combine several service responses into one before replying to the client.

💡 Hotel concierge analogy: Guests don't call housekeeping, the kitchen, and the box office separately. They ask the concierge, who knows which department handles what (routing), coordinates a multi-part request like "dinner, a show, and a taxi" (aggregation), speaks each department's language (protocol translation), and checks you're actually a guest before acting (security).

Core Functions

1. Request routing

The gateway maps incoming paths to backend services. With http-proxy-middleware in Express, each route proxies to a service URL and rewrites the path:

const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

const services = {
  user:    'http://user-service:3001',
  product: 'http://product-service:3002',
  order:   'http://order-service:3003',
};

// /api/users/42  ->  http://user-service:3001/42
app.use('/api/users', createProxyMiddleware({
  target: services.user,
  changeOrigin: true,
  pathRewrite: { '^/api/users': '' },
}));

app.use('/api/products', createProxyMiddleware({
  target: services.product,
  changeOrigin: true,
  pathRewrite: { '^/api/products': '' },
}));

app.listen(8000, () => console.log('API Gateway on :8000'));

2. Request aggregation

The gateway can fan out to several services and stitch the results into one response — the mobile client makes a single call instead of three. Fire the independent calls in parallel:

// GET /api/product-details/:id  — combine product, reviews, inventory
app.get('/api/product-details/:id', async (req, res) => {
  const { id } = req.params;
  try {
    const [product, reviews, inventory] = await Promise.all([
      fetch(`http://product-service/products/${id}`).then(r => r.json()),
      fetch(`http://review-service/reviews?productId=${id}`).then(r => r.json()),
      fetch(`http://inventory-service/inventory/${id}`).then(r => r.json()),
    ]);

    res.json({
      product,
      reviews,
      inventory,
      inStock: inventory.quantity > 0,
    });
  } catch (err) {
    console.error('Aggregation failed:', err);
    res.status(502).json({ error: 'Failed to load product details' });
  }
});

3. Protocol translation

Clients often speak HTTP/JSON while internal services use gRPC or messaging. The gateway translates between them, so clients stay simple and services use whatever is fastest internally.

Security at the Gateway

Centralizing authentication and authorization is one of the biggest wins of a gateway: verify the caller once at the edge, then forward trusted identity to services instead of every service re-implementing token checks.

const jwt = require('jsonwebtoken');
const JWT_SECRET = process.env.JWT_SECRET;

// Authentication: verify the JWT, attach identity for downstream services
function authenticate(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'No token provided' });
  }
  try {
    const decoded = jwt.verify(header.slice(7), JWT_SECRET);
    req.user = decoded;
    // Pass trusted identity to backend services as headers
    req.headers['x-user-id'] = decoded.userId;
    req.headers['x-user-role'] = decoded.role;
    next();
  } catch {
    return res.status(401).json({ error: 'Invalid token' });
  }
}

// Authorization: gate routes by role
function authorize(...allowedRoles) {
  return (req, res, next) => {
    if (!req.user) return res.status(401).json({ error: 'Not authenticated' });
    if (!allowedRoles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  };
}

// Public — no auth
app.use('/api/auth', createProxyMiddleware({ target: 'http://auth-service:3001', changeOrigin: true }));

// Protected — must be logged in
app.use('/api/users', authenticate, createProxyMiddleware({ target: 'http://user-service:3002', changeOrigin: true }));

// Admin only
app.use('/api/admin', authenticate, authorize('ADMIN'),
  createProxyMiddleware({ target: 'http://admin-service:3003', changeOrigin: true }));

Gateway Patterns

Single Gateway

One gateway for the whole system. Simplest to run and gives consistent policy enforcement, but it's a potential bottleneck and single point of failure (mitigate by running multiple replicas behind a load balancer).

Backend for Frontend (BFF)

The most popular pattern at scale: a dedicated gateway per client type, each tailored to that client's needs. This avoids one bloated gateway trying to serve wildly different clients.

Build vs. Buy

You rarely need to write a gateway from scratch. For production, a mature product handles the hard edge cases (connection pooling, hot config reloads, observability) for you.

Rate Limiting & Caching

Rate limiting

Protect backends from abuse and traffic spikes by capping how many requests a client can make. A shared store like Redis lets the limit hold across multiple gateway replicas:

const { RateLimiterRedis } = require('rate-limiter-flexible');
const Redis = require('ioredis');
const redis = new Redis({ host: 'redis-server', port: 6379 });

// 100 requests / minute for general traffic
const generalLimiter = new RateLimiterRedis({
  storeClient: redis, keyPrefix: 'general', points: 100, duration: 60,
});
// Stricter: 20 / minute for payments
const paymentLimiter = new RateLimiterRedis({
  storeClient: redis, keyPrefix: 'payment', points: 20, duration: 60,
});

function limit(limiter) {
  return async (req, res, next) => {
    const key = req.user?.userId || req.ip;   // per-user if known, else per-IP
    try {
      await limiter.consume(key);
      next();
    } catch (rej) {
      res.set('Retry-After', String(Math.ceil(rej.msBeforeNext / 1000)));
      res.status(429).json({ error: 'Too Many Requests' });
    }
  };
}

app.use(limit(generalLimiter));                 // global cap
app.use('/api/payments', limit(paymentLimiter)); // stricter on payments

Response caching

Cache responses to slow-changing, read-heavy endpoints so repeat requests skip the backend entirely. Cache only idempotent GETs and never user-specific data:

const cache = new Redis({ host: 'redis-server', port: 6379 });

function cacheFor(seconds) {
  return async (req, res, next) => {
    if (req.method !== 'GET') return next();      // never cache writes
    const key = `cache:${req.originalUrl}`;

    const hit = await cache.get(key);
    if (hit) {
      res.set('X-Cache', 'HIT');
      return res.type('application/json').send(hit);
    }

    // Intercept the response body to store it
    const originalSend = res.send.bind(res);
    res.send = (body) => {
      if (res.statusCode >= 200 && res.statusCode < 300) {
        cache.setex(key, seconds, body).catch(console.error);
      }
      res.set('X-Cache', 'MISS');
      return originalSend(body);
    };
    next();
  };
}

// Product listings change slowly — cache 5 min
app.use('/api/products', cacheFor(300),
  createProxyMiddleware({ target: 'http://product-service:3002', changeOrigin: true }));

Observability

The gateway sees every request, which makes it the ideal place to measure and trace your system. Three pillars: metrics, logging, and distributed tracing.

Metrics & logging

Track request rate, latency percentiles (p50/p90/p99), error rate, cache-hit ratio, and rate-limit rejections. Attach a request ID to every call so you can follow one request through the logs:

const { randomUUID } = require('crypto');

// Give every request a traceable ID + structured access log
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] || randomUUID();
  res.setHeader('X-Request-ID', req.id);
  const start = Date.now();

  res.on('finish', () => {
    console.log(JSON.stringify({
      requestId: req.id,
      method: req.method,
      url: req.originalUrl,
      status: res.statusCode,
      durationMs: Date.now() - start,
      userId: req.user?.userId ?? null,
    }));
  });
  next();
});

Distributed tracing

A single client request may touch many services. Distributed tracing (OpenTelemetry → Jaeger/Zipkin) propagates a shared trace ID across every hop so you can see the whole call tree and find the slow step:

The gateway starts the trace and injects the trace headers into every outgoing call, so each service continues the same trace instead of starting a fresh one.

Hands-on Exercise

const express = require('express');
const jwt = require('jsonwebtoken');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();
app.use(express.json());

const SERVICES = {
  user:    'http://localhost:3001',
  product: 'http://localhost:3002',
  order:   'http://localhost:3003',
};
const JWT_SECRET = process.env.JWT_SECRET || 'dev-secret';
const cache = new Map();  // demo cache: key -> { body, expires }

// 1) request id + logging
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] || crypto.randomUUID();
  const start = Date.now();
  res.on('finish', () =>
    console.log(`[${req.id}] ${req.method} ${req.originalUrl} ${res.statusCode} ${Date.now() - start}ms`));
  next();
});

// 2) auth
function authenticate(req, res, next) {
  const h = req.headers.authorization;
  if (!h?.startsWith('Bearer ')) return res.status(401).json({ error: 'No token' });
  try { req.user = jwt.verify(h.slice(7), JWT_SECRET); next(); }
  catch { res.status(401).json({ error: 'Invalid token' }); }
}

// 3) aggregation (register BEFORE the product proxy)
app.get('/api/product-details/:id', async (req, res) => {
  const { id } = req.params;
  const [product, inventory] = await Promise.all([
    fetch(`${SERVICES.product}/products/${id}`).then(r => r.json()),
    fetch(`${SERVICES.product}/inventory/${id}`).then(r => r.json()),
  ]);
  res.json({ product, inStock: inventory.quantity > 0 });
});

// 4) caching for product listings
function cacheFor(seconds) {
  return (req, res, next) => {
    if (req.method !== 'GET') return next();
    const key = req.originalUrl, now = Date.now(), hit = cache.get(key);
    if (hit && hit.expires > now) { res.set('X-Cache', 'HIT'); return res.json(hit.body); }
    const send = res.json.bind(res);
    res.json = (body) => { cache.set(key, { body, expires: now + seconds * 1000 }); return send(body); };
    next();
  };
}

// 5) routes
app.use('/api/products', cacheFor(300),
  createProxyMiddleware({ target: SERVICES.product, changeOrigin: true, pathRewrite: { '^/api/products': '' } }));
app.use('/api/users', authenticate,
  createProxyMiddleware({ target: SERVICES.user, changeOrigin: true, pathRewrite: { '^/api/users': '' } }));
app.use('/api/orders', authenticate,
  createProxyMiddleware({ target: SERVICES.order, changeOrigin: true, pathRewrite: { '^/api/orders': '' } }));

app.listen(8000, () => console.log('API Gateway on :8000'));

Summary & Quiz

📚 Further Reading

• microservices.io — API Gateway Pattern
• Kong Gateway Documentation
• AWS API Gateway Documentation
• Microsoft — Gateway Design Patterns

🚀 What's Next?

You've centralized the front door for your services. Next we move beyond always-on servers entirely with Serverless Computing Principles — running code as functions that scale to zero and bill per invocation.