Java Notes

API Gateway

Learn API Gateway pattern in microservices architecture with Spring Cloud Gateway - routing, filters, load balancing, rate limiting, and authentication.

What is an API Gateway?

An API Gateway is a single entry point for all client requests in a microservices architecture. Instead of clients knowing about and directly calling 10 or 20 different microservices (each with different URLs, ports, and protocols), they send all requests to one gateway URL. The gateway handles the complexity of routing each request to the appropriate backend service.

Think of it like a hotel reception desk — guests don't walk directly to housekeeping, the kitchen, or maintenance. They go to reception, which routes their request to the right department. The API Gateway serves this same role for your microservices.

Without Gateway	With Gateway:
Client	user-service:8081 Client → Gateway:8080
Client	order-service:8082 ↓
Client	payment-service:8083 Routes internally to:
Client	notification:8084 user-service

Spring Cloud Gateway Setup

Spring Cloud Gateway is the recommended gateway implementation for Spring Boot microservices. It's built on Project Reactor (non-blocking, reactive) for high throughput.

Dependencies (pom.xml):

xml example

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>

Configuration (application.yml):

yaml example

server:
  port: 8080

spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true    # Auto-discover services from Eureka
          lower-case-service-id: true
      routes:
        - id: user-service
          uri: lb://USER-SERVICE    # lb:// = load-balanced via Eureka
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1

        - id: order-service
          uri: lb://ORDER-SERVICE
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1
            - name: CircuitBreaker
              args:
                name: orderFallback
                fallbackUri: forward:/fallback/orders

        - id: payment-service
          uri: lb://PAYMENT-SERVICE
          predicates:
            - Path=/api/payments/**
            - Method=POST
          filters:
            - StripPrefix=1
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20

How this works:

A request to gateway:8080/api/users/123 is routed to USER-SERVICE/123
lb:// prefix tells Gateway to use Eureka for service discovery and load balance across instances
StripPrefix=1 removes the /api prefix before forwarding
The payment route has rate limiting (10 requests/second, burst of 20) and only accepts POST

Gateway Concepts: Predicates and Filters

Predicates determine which route matches a request (like URL pattern matching):

yaml example

predicates:
  - Path=/api/users/**           # URL path pattern
  - Method=GET,POST              # HTTP method
  - Header=X-Request-Id, \d+    # Header presence/pattern
  - Query=category, electronics  # Query parameter
  - After=2024-01-01T00:00:00Z   # Time-based routing
  - Weight=group1, 8             # Weighted routing (canary deploys)

Filters modify the request or response as it passes through:

yaml example

filters:
  - AddRequestHeader=X-Gateway-Source, spring-cloud
  - AddResponseHeader=X-Response-Time, ${responseTime}
  - StripPrefix=1
  - RewritePath=/api/(?<segment>.*), /${segment}
  - CircuitBreaker=myCircuitBreaker
  - Retry=3
  - RequestRateLimiter=10,20

Custom Global Filter for Authentication

The gateway is the ideal place to validate JWT tokens — check once at the gateway rather than in every service:

Example

@Component public class AuthenticationFilter implements GlobalFilter, Ordered { @Autowired private JwtUtil jwtUtil; private final List<String> openEndpoints = List.of( "/api/auth/login", "/api/auth/register", "/actuator/health" ); @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { String path = exchange.getRequest().getURI().getPath(); // Skip auth for open endpoints if (openEndpoints.stream().anyMatch(path::startsWith)) { return chain.filter(exchange); } // Extract and validate JWT String authHeader = exchange.getRequest().getHeaders().getFirst("Authorization"); if (authHeader == null || !authHeader.startsWith("Bearer ")) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } String token = authHeader.substring(7); try { Claims claims = jwtUtil.validateToken(token); // Add user info to headers for downstream services exchange.getRequest().mutate() .header("X-User-Id", claims.getSubject()) .header("X-User-Role", claims.get("role", String.class)) .build(); } catch (Exception e) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } return chain.filter(exchange); } @Override public int getOrder() { return -1; // Run before other filters } }

This pattern means backend services receive pre-validated user information in headers — they never need to validate JWTs themselves.

Circuit Breaker and Resilience

The gateway should protect backend services from cascading failures using circuit breakers:

java example

@Bean
public RouteLocator customRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("order-service", r -> r
            .path("/api/orders/**")
            .filters(f -> f
                .stripPrefix(1)
                .circuitBreaker(config -> config
                    .setName("orderCircuitBreaker")
                    .setFallbackUri("forward:/fallback/orders"))
                .retry(config -> config
                    .setRetries(3)
                    .setStatuses(HttpStatus.SERVICE_UNAVAILABLE)))
            .uri("lb://ORDER-SERVICE"))
        .build();
}

@RestController
public class FallbackController {
    @GetMapping("/fallback/orders")
    public ResponseEntity<Map<String, String>> orderFallback() {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(Map.of("message", "Order service is temporarily unavailable. Please try again later."));
    }
}

When the order service is down, instead of returning a cryptic error, the gateway returns a friendly fallback response and stops sending requests to the failing service (circuit opens).

Rate Limiting

Protect your services from abuse or accidental overload:

yaml example

spring:
  cloud:
    gateway:
      routes:
        - id: payment-service
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10    # 10 requests/second steady state
                redis-rate-limiter.burstCapacity: 20    # Allow brief bursts of 20
                key-resolver: "#{@userKeyResolver}"     # Rate limit per user

java example

@Bean
public KeyResolver userKeyResolver() {
    return exchange -> Mono.just(
        exchange.getRequest().getHeaders().getFirst("X-User-Id") != null
            ? exchange.getRequest().getHeaders().getFirst("X-User-Id")
            : exchange.getRequest().getRemoteAddress().getAddress().getHostAddress()
    );
}

Summary

The API Gateway is an essential pattern in microservices architecture. It provides a single entry point for all clients, centralizes cross-cutting concerns (authentication, rate limiting, logging, circuit breaking), and decouples clients from the internal service topology. Spring Cloud Gateway offers a reactive, high-performance implementation with declarative routing via predicates and filters. In production, the gateway handles JWT validation, protects services with circuit breakers and rate limiters, and enables advanced deployment patterns like canary releases through weighted routing.

Exam Focus

Revise definitions, diagrams, examples, and short-answer points for API Gateway.

Interview Use

Prepare one clear explanation, one practical example, and one common mistake for this Java Master Course topic.

Search Terms

java-master-course, java master course, java, master, course, spring, framework, microservices

Continue learning this concept

Spring FrameworkConfig ServerCentralized configuration management with Spring Cloud Config Server - externalizing configuration, Git-based config, refresh scope, and encrypted properties.Spring FrameworkDocker DeploymentContainerizing and deploying Spring Boot microservices with Docker - Dockerfile, docker-compose, multi-service deployment, and production best practices.Spring FrameworkEureka Server - Service DiscoverySetting up Netflix Eureka Server for service discovery in Spring Boot microservices - server configuration, client registration, and service communication.Spring FrameworkREST API with Spring BootBuilding RESTful APIs with Spring Boot - REST principles, controller annotations, request/response handling, pagination, HATEOAS, and API versioning.Spring FrameworkDependency InjectionComplete guide to Dependency Injection in Spring - constructor injection, setter injection, field injection, @Autowired, @Qualifier, circular dependencies, and best practices.Spring FrameworkSpring BeansComplete guide to Spring Beans - bean definition, stereotype annotations, bean naming, lazy initialization, conditional beans, and bean ordering.

PreviousDependency Injection NextConfig Server

Java Notes

API Gateway

Learn API Gateway pattern in microservices architecture with Spring Cloud Gateway - routing, filters, load balancing, rate limiting, and authentication.

What is an API Gateway?

Without Gateway	With Gateway:
Client	user-service:8081 Client → Gateway:8080
Client	order-service:8082 ↓
Client	payment-service:8083 Routes internally to:
Client	notification:8084 user-service

Spring Cloud Gateway Setup

Spring Cloud Gateway is the recommended gateway implementation for Spring Boot microservices. It's built on Project Reactor (non-blocking, reactive) for high throughput.

Dependencies (pom.xml):

xml example

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>

Configuration (application.yml):

yaml example

server:
  port: 8080

spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true    # Auto-discover services from Eureka
          lower-case-service-id: true
      routes:
        - id: user-service
          uri: lb://USER-SERVICE    # lb:// = load-balanced via Eureka
          predicates:
            - Path=/api/users/**
          filters:
            - StripPrefix=1

        - id: order-service
          uri: lb://ORDER-SERVICE
          predicates:
            - Path=/api/orders/**
          filters:
            - StripPrefix=1
            - name: CircuitBreaker
              args:
                name: orderFallback
                fallbackUri: forward:/fallback/orders

        - id: payment-service
          uri: lb://PAYMENT-SERVICE
          predicates:
            - Path=/api/payments/**
            - Method=POST
          filters:
            - StripPrefix=1
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20

How this works:

A request to gateway:8080/api/users/123 is routed to USER-SERVICE/123
lb:// prefix tells Gateway to use Eureka for service discovery and load balance across instances
StripPrefix=1 removes the /api prefix before forwarding
The payment route has rate limiting (10 requests/second, burst of 20) and only accepts POST

Gateway Concepts: Predicates and Filters

Predicates determine which route matches a request (like URL pattern matching):

yaml example

predicates:
  - Path=/api/users/**           # URL path pattern
  - Method=GET,POST              # HTTP method
  - Header=X-Request-Id, \d+    # Header presence/pattern
  - Query=category, electronics  # Query parameter
  - After=2024-01-01T00:00:00Z   # Time-based routing
  - Weight=group1, 8             # Weighted routing (canary deploys)

Filters modify the request or response as it passes through:

yaml example

filters:
  - AddRequestHeader=X-Gateway-Source, spring-cloud
  - AddResponseHeader=X-Response-Time, ${responseTime}
  - StripPrefix=1
  - RewritePath=/api/(?<segment>.*), /${segment}
  - CircuitBreaker=myCircuitBreaker
  - Retry=3
  - RequestRateLimiter=10,20

Custom Global Filter for Authentication

The gateway is the ideal place to validate JWT tokens — check once at the gateway rather than in every service:

Example

This pattern means backend services receive pre-validated user information in headers — they never need to validate JWTs themselves.

Circuit Breaker and Resilience

The gateway should protect backend services from cascading failures using circuit breakers:

java example

@Bean
public RouteLocator customRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("order-service", r -> r
            .path("/api/orders/**")
            .filters(f -> f
                .stripPrefix(1)
                .circuitBreaker(config -> config
                    .setName("orderCircuitBreaker")
                    .setFallbackUri("forward:/fallback/orders"))
                .retry(config -> config
                    .setRetries(3)
                    .setStatuses(HttpStatus.SERVICE_UNAVAILABLE)))
            .uri("lb://ORDER-SERVICE"))
        .build();
}

@RestController
public class FallbackController {
    @GetMapping("/fallback/orders")
    public ResponseEntity<Map<String, String>> orderFallback() {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(Map.of("message", "Order service is temporarily unavailable. Please try again later."));
    }
}

When the order service is down, instead of returning a cryptic error, the gateway returns a friendly fallback response and stops sending requests to the failing service (circuit opens).

Rate Limiting

Protect your services from abuse or accidental overload:

yaml example

spring:
  cloud:
    gateway:
      routes:
        - id: payment-service
          filters:
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 10    # 10 requests/second steady state
                redis-rate-limiter.burstCapacity: 20    # Allow brief bursts of 20
                key-resolver: "#{@userKeyResolver}"     # Rate limit per user

java example

@Bean
public KeyResolver userKeyResolver() {
    return exchange -> Mono.just(
        exchange.getRequest().getHeaders().getFirst("X-User-Id") != null
            ? exchange.getRequest().getHeaders().getFirst("X-User-Id")
            : exchange.getRequest().getRemoteAddress().getAddress().getHostAddress()
    );
}

Summary

Exam Focus

Revise definitions, diagrams, examples, and short-answer points for API Gateway.

Interview Use

Prepare one clear explanation, one practical example, and one common mistake for this Java Master Course topic.

Search Terms

java-master-course, java master course, java, master, course, spring, framework, microservices

Continue learning this concept

PreviousDependency Injection NextConfig Server