API Gateway Pattern

Tags

API Gateway Pattern

A single entry point for all client requests into a microservices system, responsible for cross-cutting infrastructure concerns — routing, authentication, rate limiting, TLS termination, and observability — without containing business logic.

Core Idea

In a microservices architecture, clients should not call individual services directly. Doing so exposes internal topology, requires each client to manage service discovery, and forces cross-cutting concerns (authentication, rate limiting, logging) to be reimplemented in every service.

The API Gateway is a dedicated infrastructure component that sits between external clients and internal services. Every inbound request passes through it. It applies shared policies uniformly and routes requests to the appropriate backend service or BFF-Pattern.

The API Gateway is an infrastructure pattern. It does not know about your business domain; it does not transform data for specific clients; it does not aggregate responses. These distinctions are what separate it from a BFF-Pattern.

Key Principles

  1. Single ingress point — all external traffic enters the system through the gateway; no client-to-service direct calls
  2. Cross-cutting concerns only — authentication token validation, rate limiting, TLS, logging, request ID injection; no business logic
  3. Routes, does not transform — the gateway directs traffic; it does not reshape responses for clients (that is the BFF's job)
  4. Shared infrastructure — owned by a platform/infrastructure team, not a product team; serves all clients equally
  5. High availability — because all traffic passes through it, the gateway must be treated as critical infrastructure with redundancy and careful change management

How It Works

External Client
      |
      v
[ API Gateway ]
  |-- TLS termination (HTTPS → HTTP internally)
  |-- Auth token validation (JWT signature check, OAuth2 introspection)
  |-- Rate limiting (e.g., 1000 req/min per API key)
  |-- Request ID injection (X-Request-ID header)
  |-- Routing decision:
  |     /api/web/*     → Web BFF
  |     /api/mobile/*  → Mobile BFF
  |     /api/partner/* → Partner BFF
  |-- Access logging
  v
[ BFF or Microservice ]

The gateway receives the raw request, validates it, enriches it (adds trace headers, user identity headers post-auth), and proxies it downstream. The downstream service receives an already-authenticated, already-traced, already-rate-limited request.

What API Gateway Does vs What BFF Does

This is the most important distinction for architects:

ConcernAPI GatewayBFF
TLS terminationYesNo
Rate limitingYesNo
JWT validationYes (signature only)Can check claims/scopes
RoutingYesNo (it is a destination)
Response aggregationNoYes
Data transformationNoYes
Client-specific logicNoYes
Business awarenessNoneClient-domain-specific
Team ownershipPlatform/Infra teamFrontend/Product team
Deployment cadenceSlow (infra change)Fast (product iteration)

Rule of thumb: If a concern applies to all clients equally → API Gateway. If a concern is specific to one client type → BFF.

Common Implementations

Cloud-managed:

  • AWS API Gateway — fully managed, integrates with Lambda, Cognito; limited routing flexibility
  • Azure API Management — feature-rich; strong policy engine
  • Google Cloud Apigee — enterprise-focused, developer portal included

Open-source / self-hosted:

  • Kong — Nginx-based; rich plugin ecosystem; industry standard for self-hosted
  • Traefik — cloud-native; excellent Kubernetes integration; auto-discovers services
  • Nginx / HAProxy — raw reverse proxies that can be configured as API gateways

Spring ecosystem:

  • Spring-Cloud-Gateway — Spring-native API Gateway built on WebFlux/Reactor Netty; can also serve as a thin BFF layer; integrates with Spring Security and Spring Cloud ecosystem

API Gateway Patterns

Gateway Aggregation — the gateway fans out to multiple services and aggregates (blurs into BFF territory; generally avoid this in the gateway layer)

Gateway Offloading — push cross-cutting logic from services into the gateway (auth, tracing); reduces service complexity

Gateway Routing — route by path, hostname, header, or query parameter; enables blue/green deployments, canary releases, A/B testing at the edge

Backends For Frontends — the gateway routes to different BFF-Pattern instances rather than directly to microservices; the recommended combined architecture

BFF + API Gateway: The Canonical Architecture

The most robust architecture uses both:

Internet
    |
    v
[ API Gateway ]
(Kong / AWS API GW / Spring Cloud Gateway)
Cross-cutting: TLS, rate limiting, auth token validation, routing, tracing
    |
    |── route /web/*  ──────> [ Web BFF     ] ──┐
    |── route /mobile/* ────> [ Mobile BFF  ] ──┤──> [ Microservices ]
    └── route /partner/* ───> [ Partner BFF ] ──┘

Without the API Gateway, each BFF must implement its own TLS, rate limiting, and authentication token validation — duplicating infrastructure code across teams. The Gateway handles this once; BFFs focus on aggregation.

Without BFF behind the Gateway, the Gateway itself accumulates client-specific logic and becomes a bottleneck — the same problem the BFF pattern solves.

Common Misconceptions

  • "The API Gateway and BFF are the same thing" — They solve different problems. Gateway: infrastructure and routing. BFF: client-specific aggregation. See BFF-Pattern.
  • "The API Gateway is where you put business logic" — No. This is an anti-pattern (sometimes called "smart gateway, dumb services" — the reverse of the intended design). Business logic belongs in services; orchestration belongs in BFFs; infrastructure concerns belong in the gateway.
  • "One API Gateway is always enough" — For multi-region deployments, you may have regional API Gateways. For environments with strict compliance requirements (PCI-DSS, HIPAA), you may have separate gateway tiers.
  • "The API Gateway is a single point of failure" — It is a potential one, which is why gateway infrastructure must be deployed with redundancy (multiple instances behind a load balancer) and treated with the same care as your database.

Why It Matters

In the BFF + Spring Boot context, the API Gateway is the infrastructure that:

  1. Validates OAuth2 tokens before requests reach BFFs (offloading auth validation)
  2. Enforces rate limits per client or per API key
  3. Provides the routing layer that directs traffic to the correct BFF
  4. Injects distributed tracing headers (for Zipkin/Jaeger propagation)

Spring-Cloud-Gateway is the Spring-native implementation and is the technology most commonly used in Spring Boot BFF architectures.

ConceptRelationship
BFF-PatternSits behind the API Gateway; handles client-specific aggregation
Spring-Cloud-GatewaySpring implementation of the API Gateway pattern
Service-Mesh-PatternService Mesh operates between services (east-west traffic); API Gateway handles north-south (client-to-service) traffic
OAuth2-BFF-PatternSecurity pattern that relies on Gateway → BFF → Service chain
Sam-NewmanDocumented relationship between API Gateway and BFF patterns
  • Micro-Frontends — In micro-frontends, the shell application's routing to independently deployed micro-frontends mirrors the API Gateway pattern; a single entry point routing to independent backend services.
  • REST-API-Design — API gateways route and version REST APIs; URI path versioning is trivially distinguishable in gateway routing rules
  • GraphQL-API-Design — GraphQL Federation uses a gateway layer for schema composition and subgraph routing
  • Zero-Trust-Architecture — API Gateway is the ingress enforcement point in a Zero Trust architecture; every request passing through the gateway is authenticated and authorized regardless of network origin
  • CORS-CSP — the API Gateway is typically the layer where CORS policy is enforced for browser clients; origin allowlisting happens at the gateway, not at individual services
  • Input-Validation — the gateway is the first trust boundary for external input; schema validation and request size limits are gateway-level responsibilities

Sources

  • Sam Newman, "Building Microservices" 2nd ed. (O'Reilly, 2021) — Chapter 14: User Interfaces
  • Chris Richardson, "Microservices Patterns" (Manning, 2018) — API Gateway chapter
  • Kong API Gateway documentation — gateway capabilities and plugin model
  • AWS API Gateway developer guide
  • Thoughtworks Technology Radar — API Gateway "adopt" recommendation

Linked mentions