Skip to content
System Design Lab
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.

Beginner 6 min read· Updated 2026-11-18

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

BeforeDirect client-to-service
Mobile appknows every servi…Mobile appOrdersown auth + CORSOrdersUsersown auth + CORSUsersCatalogown auth + CORSCatalog
Every client knows every service address, and every service re-implements authentication, CORS and throttling.
AfterWith a gateway
Web & mobile a…one public endpoi…Web & mobile appsAPI Gatewayauth · limits · r…API GatewayOrders Service/ordersOrders ServiceUsers Service/usersUsers ServiceCatalog Service/catalogCatalog Service
One public endpoint; services stay private and focus on business logic.
  • 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

ResponsibilityExample
Routing/orders/** → Orders Service, /catalog/** → Catalog Service.
Edge security (offloading)Validate the JWT once; pass the user id downstream in a trusted header.
Rate limiting25 requests/s per API key using a token bucket; answer 429 beyond that.
AggregationGET /home calls three services in parallel and merges the result.
Protocol translationPublic REST/JSON in front of internal gRPC services.
Mobile appAPI GatewayUsersOrdersCatalog

Press play or step through the interaction.

Aggregation: one client request, three parallel backend calls, a partial answer when one fails.

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.

Loading simulation…

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

application.yml
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
GatewayConfig.java
@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

BenefitsCosts
Client simplicityOne host, one auth flow, fewer round trips.Client-specific logic piles up in the gateway unless you split it into BFFs.
SecurityServices are private; policies are enforced consistently.The gateway is a high-value target and must be hardened and patched.
AvailabilityCentral place for retries, timeouts and circuit breakers.A new critical component: run several instances behind a load balancer.
LatencyAggregation 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.

Further reading

Related topics