API gateways (Spring Cloud Gateway)

A gateway is the single front door of a set of microservices. It routes each request to the right service and applies cross-cutting rules (authentication, rate limiting, headers) in one place.

A mental model

The reception desk of a large office building. Visitors say who they want; reception checks ID, hands out a badge and points them to the correct floor, so no department needs its own security.

How it works

A route is: a predicate (which requests match, for example path /orders/**), a target URI (lb://order-service) and filters (strip a prefix, add a header, rate limit, retry).

Routes are declared in YAML or in Java with RouteLocatorBuilder: builder.routes().route("orders", r -> r.path("/orders/**").uri("lb://order-service")).build().

A GlobalFilter runs for every route and is the right place for token checks, correlation ids and logging. A GatewayFilter applies to chosen routes.

With service discovery, lb://name picks a healthy instance of that service each time.

Going deeper

Filters are reactive: they receive the exchange and the chain, and must return a Mono<Void>. Blocking inside a filter blocks the whole gateway, which has few threads.

Do authentication at the edge but also inside services. A gateway bypass (a service reachable directly in the cluster) otherwise exposes everything.

Keep business logic out of the gateway. It becomes a hidden monolith and a single point of failure if it grows rules and database access.

Under the hood

The gateway is a WebFlux application on Netty. A RoutePredicateHandlerMapping evaluates predicates in order, the matching route builds a filter chain (global filters merged with route filters, ordered), and the last filter proxies the request with a reactive HTTP client and streams the response back.

Common mistakes

• Blocking calls inside gateway filters.
• Trusting the gateway as the only security layer.
• Business logic in the gateway.
• No timeouts on routes, so slow services pile up requests.