Microservice Patterns
API Gateway
Give clients one entry point that routes requests to the right service and handles authentication, rate limiting and response aggregation in one place.
What you will learn
- Explain what goes wrong when every client talks to every microservice directly.
- Describe the gateway's jobs: routing, edge security, rate limiting and aggregation.
- Reason about aggregation latency and partial responses.
- Configure routes, JWT validation and rate limiting with Spring Cloud Gateway.
Overview
A hotel has one reception desk. Guests do not wander into the kitchen, the laundry and the accounts office to ask for things — reception checks who they are and passes requests to the right department. An API gateway is the reception desk of a microservice system.
An API gateway is a reverse proxy that sits between clients and backend services. Clients call one host; the gateway decides which service handles each request, enforces cross-cutting policies (authentication, rate limits, CORS, TLS) and can combine several backend calls into one response.
The problem: clients that know too much
- Coupling — splitting or renaming a service breaks every mobile app version in the wild.
- Chatty clients — a home screen needs three round trips over a slow mobile network.
- Duplicated edge logic — token validation, CORS and throttling copied into every service, each slightly different.
- Larger attack surface — every service is exposed to the internet.
What the gateway does
| Responsibility | Example |
|---|---|
| Routing | /orders/** → Orders Service, /catalog/** → Catalog Service. |
| Edge security (offloading) | Validate the JWT once; pass the user id downstream in a trusted header. |
| Rate limiting | 25 requests/s per API key using a token bucket; answer 429 beyond that. |
| Aggregation | GET /home calls three services in parallel and merges the result. |
| Protocol translation | Public REST/JSON in front of internal gRPC services. |
Press play or step through the interaction.
Run it
Scenario B is the interesting one: turn token validation off and watch unauthenticated requests reach the services. In scenario C inject Catalog slow — the aggregated latency follows the slowest backend.
One gateway or several? Backends for Frontends Advanced
Advanced A single gateway serving web, mobile and partner APIs tends to grow into a monolith of client-specific endpoints owned by nobody. The Backend for Frontend (BFF) variant gives each client experience its own gateway, owned by the team that builds that client. Shared concerns (TLS, WAF, coarse rate limits) stay in an edge layer in front of the BFFs.
Implementation with Spring Cloud Gateway
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://auth.example.com/realms/shop
cloud:
gateway:
server:
webflux: # Spring Cloud Gateway 4.3+; older versions: spring.cloud.gateway.routes
routes:
- id: orders
uri: lb://orders-service
predicates:
- Path=/orders/**
filters:
- name: RequestRateLimiter
args:
redis-rate-limiter.replenishRate: 25
redis-rate-limiter.burstCapacity: 50
key-resolver: "#{@userKeyResolver}"
- id: catalog
uri: lb://catalog-service
predicates:
- Path=/catalog/**
filters:
- name: CircuitBreaker
args:
name: catalog
fallbackUri: forward:/fallback/catalog@Configuration
class GatewayConfig {
/** Rate-limit per authenticated user (falls back to client IP). */
@Bean
KeyResolver userKeyResolver() {
return exchange -> exchange.getPrincipal()
.map(Principal::getName)
.switchIfEmpty(Mono.justOrEmpty(exchange.getRequest().getRemoteAddress())
.map(address -> address.getAddress().getHostAddress()));
}
}Trade-offs
| Benefits | Costs | |
|---|---|---|
| Client simplicity | One host, one auth flow, fewer round trips. | Client-specific logic piles up in the gateway unless you split it into BFFs. |
| Security | Services are private; policies are enforced consistently. | The gateway is a high-value target and must be hardened and patched. |
| Availability | Central place for retries, timeouts and circuit breakers. | A new critical component: run several instances behind a load balancer. |
| Latency | Aggregation saves client round trips. | Adds one network hop to every request. |
Production considerations
- Keep business logic out of the gateway — it routes and protects; services decide.
- Give each route its own Timeout and Circuit Breaker so one slow service cannot exhaust the gateway.
- Distributed rate limiting needs shared state (Redis) — per-instance limits multiply with the number of gateway replicas.
- Propagate a correlation id from the gateway so a request can be traced through every service.