API Gateway Pattern

Overview

The API Gateway is a single entry point that sits between external clients and a backend microservices architecture. Instead of clients calling individual services directly, all requests flow through the gateway, which handles cross-cutting concerns and routes requests to the appropriate service.

Without a gateway, every client must know the addresses of every service, implement its own authentication logic, handle service discovery, and manage retries and timeouts independently. The gateway centralizes these responsibilities into one component.

Real-world implementations:

• Kong -- open-source, plugin-based gateway built on NGINX
• AWS API Gateway -- managed service with Lambda integration and request transformation
• Envoy Proxy -- high-performance L4/L7 proxy, foundation of Istio service mesh
• NGINX -- widely used as a reverse proxy and gateway
• Spring Cloud Gateway -- JVM-based gateway with Spring ecosystem integration
• Traefik -- cloud-native gateway with automatic service discovery

Architecture

Client Layer

Three types of external consumers connect to the gateway over HTTPS:

• Web Client -- browser-based single-page application, authenticates via JWT
• Mobile Client -- native mobile app, may require aggregated responses to reduce round-trips
• Third-Party Client -- external integrator, authenticates via API key

API Gateway Pipeline

Incoming requests pass through a sequential pipeline of middleware components:

1. Rate Limiter -- enforces per-client request quotas (e.g., 100 requests/minute). Rejects excess traffic with HTTP 429 before it reaches any backend service.
2. Auth / JWT Validator -- validates Bearer tokens (signature, expiry, claims) or API keys. Rejects unauthenticated requests with HTTP 401.
3. Router / Dispatcher -- matches the request path to a backend service route and forwards the request via gRPC.

Backend Services

Three independently deployed services, each owning its own database (database-per-service pattern):

• User Service + Users DB -- profiles, accounts, preferences
• Product Service + Products DB -- catalog, inventory, pricing
• Order Service + Orders DB -- orders, checkout, payment orchestration

Key Concepts

Cross-Cutting Concerns

The gateway centralizes logic that would otherwise be duplicated across every service:

Authentication and Authorization: Token validation happens once at the gateway. Backend services receive pre-validated auth context (user ID, roles, scopes) and trust the gateway's decision. This eliminates redundant auth logic in every service.

Rate Limiting: Protects backend services from traffic spikes and abuse. Common algorithms include fixed window, sliding window, token bucket, and leaky bucket. Rate limits can be applied per client IP, per API key, or per user.

Routing: Path-based or header-based routing maps incoming URLs to backend services. The gateway also handles protocol translation (e.g., HTTPS from clients to gRPC toward services).

TLS Termination: The gateway terminates TLS connections from clients. Internal traffic between the gateway and backend services can use mutual TLS or plain-text within a trusted network boundary.

Logging and Observability: Centralized access logging, request tracing (correlation IDs), and metrics collection. Every request that enters or leaves the system is recorded in one place.

Gateway vs BFF vs API Composition

These three concepts are often conflated but serve different purposes:

API Gateway: A pure infrastructure component. It handles routing, auth, rate limiting, and TLS termination. It does not understand business logic or transform response payloads. It forwards requests to exactly one backend service per incoming request.

Backend-for-Frontend (BFF): A service layer tailored to a specific client type (mobile, web, TV). A mobile BFF might aggregate data from multiple backend services into a single optimized response, reshape payloads to minimize bandwidth, or filter fields the mobile client does not need. Each client type gets its own BFF.

API Composition: The act of fanning out a single client request to multiple backend services, waiting for all responses, and merging them into one payload. This is technically a BFF responsibility, not a pure gateway concern. However, many real-world gateways (Kong, AWS API Gateway, Spring Cloud Gateway) support composition via plugins or request transformers because the boundary between gateway and BFF is blurred in practice.

The script includes an API Composition scenario that demonstrates fan-out and merge. It is labeled as a BFF-style pattern to make the architectural distinction clear: a pure gateway would not do this, but many production gateways do.

Gateway Anti-Patterns

Business Logic in the Gateway: The gateway should remain a thin routing and policy layer. Moving validation rules, data transformations, or orchestration logic into the gateway couples it to service internals and makes it a bottleneck for development teams.

Single Point of Failure: A gateway that is not deployed with high availability becomes a single point of failure for the entire system. Production gateways must run as a cluster behind a load balancer, with health checks, graceful failover, and zero-downtime deployments.

Monolithic Gateway: A single gateway that handles all routes for all services can become a deployment bottleneck. Large organizations sometimes use multiple gateways (or gateway instances with separate configurations) scoped to different domains or teams.

Response Transformation Creep: Starting with minor payload adjustments (renaming a field, filtering nulls) and gradually turning the gateway into a full data transformation layer. This belongs in a BFF or service layer.

Scenarios

1. Normal Request Flow -- A web client sends an authenticated request through the full gateway pipeline (rate limiter, JWT validation, routing) to the User Service, which queries its database and returns the response back through the pipeline.
2. Rate Limiting -- A third-party client exceeds its rate limit quota. The gateway rejects the request with HTTP 429 before any backend service is contacted. After the rate limit window resets, the retry succeeds.
3. API Composition -- A mobile client requests a dashboard endpoint that requires data from both User Service and Product Service. The gateway fans out parallel requests to both services, waits for responses, and merges them into a single payload. This is a BFF-style pattern -- pure gateways typically do not aggregate.
4. Authentication Failure -- A web client sends a request with an expired JWT. The gateway rejects it with HTTP 401 at the auth layer, protecting backend services from unauthorized access. After the client refreshes its token, the retry succeeds.