Skip to content
Tutorials Center
My learning

Topics

Lesson 105 of 119 ยท Spring Cloud

API Gateway with Spring Cloud Gateway

Build an API gateway - routes, predicates and filters, rate limiting, authentication at the edge and request aggregation, with runnable Java demos and Spring Cloud Gateway.

A mobile app that talks to your microservices shouldn't need to know that users live on one service, orders on another and recommendations on a third. It shouldn't hold a list of internal addresses, and each service shouldn't have to implement authentication, rate limiting and CORS on its own. An API gateway solves all of this: it is the one public entry point that receives every external request, applies shared policies, and forwards the request to the right service.

Microservices showed a gateway that routes by path prefix and returns 502 when a service is down. This lesson goes further. You'll build a route matcher with predicates and filters, a filter chain with "pre" and "post" logic, a per-client rate limiter that answers 429, token checking at the edge, and an aggregation endpoint that combines two services into one response. Each runnable example is plain Java with real HTTP servers on 127.0.0.1 (our runner has no Spring Cloud); then you'll see how Spring Cloud Gateway expresses the same ideas in YAML and Java, read-only.

What a gateway does

Typical gateway responsibilities:

  • Routing: /api/users/** goes to user-service, /api/orders/** to order-service, usually resolved through service discovery and load balancing.
  • Authentication: reject requests without a valid token before they reach any service.
  • Rate limiting and quotas: protect services from abusive or buggy clients.
  • Cross-cutting headers: request ids for tracing, security headers, removing internal headers from responses.
  • CORS and TLS termination: handled once for every service.
  • Request and response shaping: path rewriting, API versioning, and aggregation of several service calls into one response.
  • Resilience: timeouts, retries and circuit breakers per route.

What a gateway should not do is business logic. If you find order-pricing rules in the gateway, they belong in a service. A gateway full of logic becomes a new monolith that every team must change and deploy together.

It's also easy to confuse a gateway with its neighbors:

Component Main job Sees
Load balancer Spread connections across instances of one service Mostly TCP/HTTP, no API knowledge
API gateway Route external requests to many services and apply API policies Paths, methods, headers, tokens
Service mesh (Istio, Linkerd) Retries, mTLS and telemetry for service-to-service traffic, via sidecar proxies Every internal call
Backend for frontend (BFF) A gateway tailored to one client type (web, mobile) Shapes data for that client

Routes, predicates and filters

Spring Cloud Gateway models everything with three concepts:

  • A route has an id, a destination URI, a list of predicates and a list of filters.
  • A predicate is a test on the incoming request: path pattern, HTTP method, header, host, query parameter, time window, or a weight for traffic splitting. A route matches only if all its predicates are true. Routes are checked in order, and the first match wins.
  • A filter changes the request before it's forwarded or the response before it's returned: strip a path prefix, add a header, rewrite the path, limit the rate.

The program below implements a small route table with exactly these pieces. The second route only matches requests with an X-Api-Version: 2 header, so it has to come before the general orders route, otherwise it would never be reached:

Java A route table with predicates and filters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Read the results carefully. DELETE /api/users/42 got a 404 because the users route only allows GET and POST. /api/ordersXYZ didn't match /api/orders/**: a path pattern matches whole segments, not string prefixes, which is a real difference from the naive startsWith you may have seen before. And the versioned request was rewritten to /v2/orders/7 with a regular expression, while the plain one only lost its /api prefix.

Pre and post filters: the filter chain

Some filters need to act twice: once on the way in and once on the way out. A timing filter records the start time, lets the request through, and adds a Server-Timing header to the response. Gateways (like servlet filters in Filters and Listeners) implement this as a chain: each filter receives the request and a chain object, does its "pre" work, calls chain.next(...) to pass the request on, then does its "post" work on the response that comes back.

This gateway runs for real on HTTP. Two filters apply to every route (global filters): one adds a request id and the client's address in X-Forwarded-For, the other removes an internal header that a backend leaks in its responses. The last link in the chain forwards the request to the backend.

Java A real HTTP gateway with a pre and post filter chain

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The backends saw the request id and the original client address, which the gateway added on the way in; the client got the same request id back, added on the way out, and never saw X-Internal-Host. Notice how small each filter is. Because filters are independent links in a chain, you can add, remove and reorder them per route without touching the others.

Rate limiting

A rate limiter caps how many requests a client may send. Without one, a single buggy script that calls your API in a tight loop can starve every other user. The usual algorithm is the token bucket: each client has a bucket that holds up to burstCapacity tokens and refills at replenishRate tokens per second. Every request takes one token; with an empty bucket the gateway answers 429 Too Many Requests without calling any service. The bucket allows short bursts but enforces the average rate.

The limiter needs a key that identifies the client: an API key, a user id from the token, or the IP address. Here the key is the X-Api-Key header, and the clock is simulated so the run is repeatable:

Java Token-bucket rate limiting per API key with 429 responses

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Alice's burst of three succeeded and the fourth request was rejected with 429. Bob has his own bucket, so Alice's burst didn't affect him. Half a second later alice still had only half a token; after one second she had one again. After a quiet period her bucket refilled to its capacity of three, but never beyond. The request without an API key was refused with 403, the same choice Spring Cloud Gateway makes by default when the key resolver finds no key.

One detail matters in production: the buckets here live in one gateway's memory. With three gateway instances behind a load balancer, each would allow the full rate, tripling the real limit. Spring Cloud Gateway therefore stores buckets in Redis, shared by all instances.

Authentication at the edge

The gateway is the natural place to reject unauthenticated traffic early: invalid requests never consume service resources. A common design is that clients send a JWT (see JWT and OAuth 2); the gateway verifies the signature and expiry, then forwards the request with the token, and possibly with extracted identity headers such as X-User-Id.

That last part hides a classic security hole. If services trust X-User-Id, a client can simply send that header itself. The gateway must remove any incoming copy before adding its own. The demo uses a simplified signed token (userId.signature, signed with HMAC-SHA256) in place of a full JWT:

Java Verifying tokens at the gateway and stopping header spoofing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The forged token reused alice's signature with a different user name, and the signature check caught it. The spoofed X-User-Id: admin header was simply never forwarded, so the service saw the verified alice. Two more rules complete the picture: services must only be reachable through the gateway (private network, or mutual TLS), otherwise attackers skip it; and many teams let services verify the relayed JWT themselves too ("zero trust"), instead of trusting gateway headers blindly.

Aggregation: one request, several services

A mobile dashboard might need the user's profile and their recent orders. Making the phone send two requests over a slow mobile network doubles the latency. The gateway (or a dedicated backend for frontend) can aggregate: receive one request, call both services in parallel, and merge the results into one JSON document. If one part fails, it can still return the rest, marked as unavailable.

Java Aggregating two services in parallel

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Both 300 ms calls ran at the same time, so the whole response took about 300 ms instead of 600 ms, and the broken recommendation service produced a labeled gap instead of an error page. Keep aggregation thin: combining and reshaping data is fine at the edge; computing business results is not.

Spring Cloud Gateway

Spring Cloud Gateway comes in two flavors that share the route/predicate/filter model:

Gateway Server WebFlux Gateway Server MVC
Starter spring-cloud-starter-gateway-server-webflux spring-cloud-starter-gateway-server-webmvc
Runtime Reactive, Netty, non-blocking Servlet stack (Tomcat), works well with virtual threads
Property prefix spring.cloud.gateway.server.webflux spring.cloud.gateway.server.webmvc
Java DSL RouteLocatorBuilder RouterFunction with gateway handler functions
Choose it when Very high concurrency, streaming, existing reactive code Your team prefers blocking code and Spring MVC

The WebFlux flavor is the original and most feature-rich. The starter and property names above are the ones introduced with the 2025.0 release train; older projects use spring-cloud-starter-gateway and spring.cloud.gateway.routes. Check the current release train before copying names.

Routes in YAML

The YAML below expresses the route table from the first demo, plus a global default filter, rate limiting and CORS. lb:// URIs go through discovery and Spring Cloud LoadBalancer:

YAML
spring:
  cloud:
    gateway:
      server:
        webflux:
          default-filters:                    # applied to every route
            - AddResponseHeader=X-Gateway, edge
            - RemoveResponseHeader=X-Internal-Host
          routes:
            - id: users
              uri: lb://user-service
              predicates:
                - Path=/api/users/**
                - Method=GET,POST
              filters:
                - StripPrefix=1
                - name: RequestRateLimiter
                  args:
                    redis-rate-limiter.replenishRate: 10     # tokens added per second
                    redis-rate-limiter.burstCapacity: 20     # bucket size
                    redis-rate-limiter.requestedTokens: 1    # cost of one request
                    key-resolver: "#{@apiKeyResolver}"
            - id: orders-v2                                  # listed before the general route
              uri: lb://order-service-v2
              predicates:
                - Path=/api/orders/**
                - Header=X-Api-Version, 2
              filters:
                - RewritePath=/api/orders/(?<rest>.*), /v2/orders/$\{rest}
            - id: orders
              uri: lb://order-service
              predicates:
                - Path=/api/orders/**
              filters:
                - StripPrefix=1
          globalcors:
            cors-configurations:
              '[/**]':
                allowed-origins: "https://app.example.com"
                allowed-methods: GET,POST,PUT,DELETE

The short form Name=arg1, arg2 is a shortcut for name: plus args:. In RewritePath, $\{rest} is escaped so Spring's property placeholder syntax doesn't swallow it. Other built-in predicates include Host, Query, Cookie, After/Before/Between (time windows) and Weight (send, say, 10% of traffic to a canary). Other filters include AddRequestHeader, SetPath, PrefixPath, Retry, CircuitBreaker, SetStatus, RedirectTo and TokenRelay.

RequestRateLimiter uses a Redis token bucket (add spring-boot-starter-data-redis-reactive), answers 429 when the bucket is empty and adds X-RateLimit-* headers. The key comes from a KeyResolver bean:

Java
@Configuration
class GatewayConfig {

    @Bean
    KeyResolver apiKeyResolver() {
        return exchange -> Mono.justOrEmpty(exchange.getRequest().getHeaders().getFirst("X-Api-Key"));
    }
}

An empty key means the request is denied, as in the demo. For limits per user, resolve the authenticated principal's name instead.

Routes and global filters in Java

The same routes can be built in Java, which helps when they depend on code or conditions:

Java
@Bean
RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("users", r -> r.path("/api/users/**").and().method("GET", "POST")
                    .filters(f -> f.stripPrefix(1).addRequestHeader("X-Gateway", "edge"))
                    .uri("lb://user-service"))
            .route("orders", r -> r.path("/api/orders/**")
                    .filters(f -> f.stripPrefix(1)
                            .circuitBreaker(c -> c.setName("orders").setFallbackUri("forward:/fallback/orders")))
                    .uri("lb://order-service"))
            .build();
}

A global filter runs for every route, like the request-id filter in the chain demo. In the reactive gateway the "post" part is attached to the Mono that completes when the response is done:

Java
@Component
class RequestIdFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String requestId = UUID.randomUUID().toString();
        ServerHttpRequest request = exchange.getRequest().mutate()
                .header("X-Request-Id", requestId)                          // pre
                .build();
        exchange.getResponse().getHeaders().add("X-Request-Id", requestId);
        long start = System.nanoTime();
        return chain.filter(exchange.mutate().request(request).build())
                .doFinally(signal -> log.info("{} took {} ms", requestId,  // post
                        (System.nanoTime() - start) / 1_000_000));
    }

    @Override
    public int getOrder() {
        return -1;                       // run early
    }
}

With Gateway Server MVC, routes are functional RouterFunction beans. The static imports come from the gateway's handler, filter and predicate packages (names have moved between versions, so let your IDE find them):

Java
@Bean
RouterFunction<ServerResponse> userRoutes() {
    return route("users")
            .route(path("/api/users/**"), http())
            .filter(lb("user-service"))
            .before(stripPrefix(1))
            .before(addRequestHeader("X-Gateway", "edge"))
            .build();
}

The MVC flavor has its own rate-limit filter (based on Bucket4j) and reads YAML routes under spring.cloud.gateway.server.webmvc.routes.

Security and token relay

Add Spring Security to the gateway to validate JWTs before routing. For the reactive gateway that's spring-boot-starter-oauth2-resource-server and a SecurityWebFilterChain; the issuer goes in spring.security.oauth2.resourceserver.jwt.issuer-uri. The Authorization header passes through to services by default, so they can verify the token again. When the gateway itself logs users in with OAuth 2 (a backend for frontend for a browser app), the TokenRelay filter takes the access token from the user's session and adds it as a bearer token to the forwarded request, so the browser never handles tokens at all. Spring Security covers the security configuration.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Route A has predicates Path=/api/orders/** and Header=X-Api-Version, 2. Route B has only Path=/api/orders/**. B is listed first. What happens to a request with X-Api-Version 2?

    Order decides, not specificity. Put narrower routes before broader ones, or set their order explicitly.
  2. 2. A token bucket has burstCapacity 3 and replenishRate 1 per second. A full bucket receives 5 requests at the same instant. What do they get?

    The burst capacity allows three immediate requests. Further requests must wait for tokens to refill, so they are rejected with 429.
  3. 3. Your services trust an X-User-Id header set by the gateway. What must the gateway do with an X-User-Id header sent by the client?

    Any client can send any header. If the gateway copies it, a user with a valid token can impersonate anyone by sending X-User-Id with another id.
  4. 4. Three gateway instances each keep rate-limit buckets in their own memory, with a limit of 10 requests per second per key. What is the effective limit?

    Load balancing spreads one client's requests across instances, each with its own bucket. That's why Spring Cloud Gateway keeps buckets in shared Redis.
  5. 5. An aggregation endpoint calls two services that take 300 ms each. Why did the demo finish in about 300 ms?

    Starting all calls before joining any of them makes the total time roughly that of the slowest call, not the sum.

Summary

  • An API gateway is the single entry point for external clients: routing, authentication, rate limiting, CORS, headers, aggregation and per-route resilience. It should hold no business logic.
  • Spring Cloud Gateway's model: routes with a URI (often lb://service), predicates that must all match (first matching route wins, so order matters) and filters that change requests and responses.
  • Filters form a chain with pre and post logic; global filters apply to every route.
  • Rate limiting uses token buckets keyed by API key, user or IP and answers 429; keep buckets in Redis when you run several gateway instances.
  • Verify tokens at the edge, strip identity headers sent by clients before adding your own, and keep services reachable only through the gateway.
  • Aggregation calls services in parallel and returns partial results when one fails.
  • Choose Gateway Server WebFlux (reactive, RouteLocatorBuilder) or Gateway Server MVC (servlet, RouterFunction); configure routes in YAML under spring.cloud.gateway.server.webflux or .webmvc.

Next: Centralized Configuration with Spring Cloud Config