Building an API Gateway with Spring Cloud Gateway

Hello! Welcome to the fifth lesson in our module on Inter-Service Communication Patterns.

In our last lesson, we established the critical need for service discovery in a dynamic microservices environment. We contrasted the client-side discovery pattern (where the client is "smart") with the server-side pattern (where a central router is "smart"). You learned that server-side discovery simplifies clients and centralizes control, often implemented by a component known as an API Gateway.

Today, we transition from theory to practice. We will build that central router. By the end of this lesson, you will be able to implement an API Gateway using Spring Cloud Gateway for routing, rate limiting, and request transformation. This is a cornerstone skill for building production-ready microservices and a frequent topic in system design interviews.

1. The Role of an API Gateway

Before we dive into code, let's solidify our understanding of what an API Gateway does and why it's indispensable. In a microservices architecture, the gateway acts as the single entry point for all external client requests. It's a façade that hides the complexity of the internal system.

To get a comprehensive overview of the gateway's responsibilities, let's watch a segment from a talk at Spring I/O.

As the video highlighted, an API Gateway is much more than a simple reverse proxy. It handles a suite of critical tasks, allowing your downstream microservices to focus purely on their business logic.

2. Introducing Spring Cloud Gateway

In the Spring ecosystem, the modern, go-to solution for building an API Gateway is Spring Cloud Gateway. It's built on a reactive foundation (Project Reactor, Spring WebFlux, and Netty), making it non-blocking and capable of handling high concurrency with minimal resource usage—a perfect fit for an edge service that must be highly performant and resilient.

The architecture of Spring Cloud Gateway is based on a few simple concepts:

• Route: The basic building block. It has a unique ID, a destination URI, a collection of predicates, and a collection of filters.
• Predicate: A condition that must be met for a request to be matched to a route. This could be based on the request path, host, headers, etc.
• Filter: Logic that can modify the incoming request before it's routed or the outgoing response after it returns from the downstream service.

You can configure routes in two ways:

1. Declaratively: Using your application.yml or application.properties file. This is the most common and straightforward method.
2. Programmatically: By defining a RouteLocator Spring bean. This offers more power for dynamic or conditional routing logic.

We will focus on the declarative approach as it's sufficient for most use cases and is easier to manage.

3. Implementing Core Functionality

Let's implement the three key features mentioned in our learning outcome: routing, transformation, and rate limiting.

Step 1: Project Setup

To create a Spring Cloud Gateway service, you start a new Spring Boot project and add the spring-cloud-starter-gateway dependency. Since our gateway will eventually discover other services, we'll also include the Eureka client dependency we discussed in the last lesson.

In your pom.xml, you would include:

<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>

And in your main application class, enable discovery:

@SpringBootApplication
@EnableDiscoveryClient
public class ApiGatewayApplication {
    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
}

Step 2: Implementing Routing

Routing is the gateway's primary job. Let's say we have a product-service and an order-service. We want to route requests starting with /products/** to the product service and /orders/** to the order service.

The uri property is key here. While you can use a static URL like http://localhost:8081, the real power comes from integrating with service discovery. By using lb://SERVICE-NAME, we tell the gateway to look up the service in Eureka (or another service registry) and load-balance the request across available instances.

Here is the configuration in application.yml:

spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true # Enables discovery integration
          lower-case-service-id: true
      routes:
        - id: product-service-route
          uri: lb://product-service # "lb" stands for load-balanced
          predicates:
            - Path=/products/**

        - id: order-service-route
          uri: lb://order-service
          predicates:
            - Path=/orders/**

With this configuration, a request to http://api-gateway:8080/products/123 will be forwarded to a healthy instance of product-service at the path /products/123.

Step 3: Implementing Request Transformation with Filters

Filters allow us to modify the request and response. This is essential for adapting requests from external clients to what internal services expect.

Let's enhance our order-service route. Imagine the service's endpoints are actually prefixed with /api/v1, so it expects requests like /api/v1/orders/456. The external API, however, should be clean (/orders/456). We can use filters to handle this transformation.

• StripPrefix=1: This filter removes the first segment of the path. So, /orders/456 becomes /456.
• PrefixPath=/api/v1/orders: This filter adds a prefix to the path.

Combining these, we can transform /orders/456 into /api/v1/orders/456.

Another common use case is adding headers, for example, to trace a request's origin.

spring:
  cloud:
    gateway:
      routes:
        - id: order-service-route
          uri: lb://order-service
          predicates:
            - Path=/orders/**
          filters:
            # Transformation 1: Rewrite the path
            - StripPrefix=1
            - PrefixPath=/api/v1/orders
            # Transformation 2: Add a request header
            - AddRequestHeader=X-Request-Source, api-gateway

This configuration now does the following for a request to /orders/456:

1. Matches the Path=/orders/** predicate.
2. Applies the StripPrefix=1 filter, changing the path to /456.
3. Applies the PrefixPath filter, changing the path to /api/v1/orders/456.
4. Applies the AddRequestHeader filter, adding X-Request-Source: api-gateway.
5. Forwards the modified request to the order-service.

You can even modify the request or response body. This is a more advanced feature, but it's incredibly powerful for tasks like masking sensitive data in a response before it leaves your system.

Step 4: Implementing Rate Limiting

A critical responsibility of a gateway is to protect your backend services from being overwhelmed. Rate limiting restricts how many requests a client can make in a given time period.

Spring Cloud Gateway provides a RequestRateLimiter filter that works with Redis to implement a distributed rate limiter based on the Token Bucket algorithm.

To see how this is implemented step-by-step, let's watch a detailed tutorial.

Let's summarize the key implementation pieces from the video.

1. Add Redis Dependency:

   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-data-redis-reactive</artifactId>
   </dependency>
   

2. Configure the Filter in application.yml:

   spring:
     cloud:
       gateway:
         routes:
           - id: rate-limited-route
             uri: lb://some-service
             predicates:
               - Path=/api/limited/**
             filters:
               - name: RequestRateLimiter
                 args:
                   # Tells the filter to use our custom KeyResolver bean
                   key-resolver: "#{@ipKeyResolver}" 
                   # The rate limiter implementation (provided by Spring)
                   redis-rate-limiter.replenishRate: 10 # 10 requests per second
                   redis-rate-limiter.burstCapacity: 20 # Allows a burst of 20 requests
   

3. Implement the KeyResolver: This is the most important part from a design perspective. It determines the "key" for rate limiting. Here's a common implementation that uses the client's IP address.

   import org.springframework.cloud.gateway.filter.ratelimiter.KeyResolver;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.web.server.ServerWebExchange;
   import reactor.core.publisher.Mono;
   
   @Configuration
   public class GatewayConfig {
   
       @Bean
       public KeyResolver ipKeyResolver() {
           // Return a Mono<String> representing the key.
           // In an interview, you could discuss using a JWT claim instead.
           return exchange -> Mono.just(exchange.getRequest().getRemoteAddress().getAddress().getHostAddress());
       }
   }
   

   The name of this bean, ipKeyResolver, is referenced in the key-resolver argument in our YAML file.

spring:
  cloud:
    gateway:
      routes:
        - id: payment-service-route
          uri: lb://payment-service
          predicates:
            - Path=/payments/**
          filters:
            # Rewrite /payments/** to /v2/process-payment/**
            - RewritePath=/payments/(?<segment>.*), /v2/process-payment/$\{segment}
            # Apply rate limiting using a bean named 'userKeyResolver'
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@userKeyResolver}"
                redis-rate-limiter.replenishRate: 2
                redis-rate-limiter.burstCapacity: 5

import org.springframework.cloud.gateway.filter.ratelimiter.KeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;

@Configuration
public class GatewayConfig {

    @Bean
    public KeyResolver userKeyResolver() {
        return exchange -> {
            // This is a simplified example. In a real app, you would
            // parse the JWT from the 'Authorization' header to get the 'sub' claim.
            // For example: return getClaim(exchange, "sub");
            // Here, we'll simulate getting it from a header for simplicity.
            String userId = exchange.getRequest().getHeaders().getFirst("X-User-ID");
            return Mono.just(userId != null ? userId : "anonymous");
        };
    }
}

Conclusion

Congratulations! You have now learned how to implement a fully functional API Gateway using Spring Cloud Gateway. This is a massive step towards building a robust and production-ready microservices system.

Key Takeaways:

• API Gateway as a Façade: It's the single entry point that centralizes cross-cutting concerns like routing, security, and rate limiting.
• Spring Cloud Gateway: A modern, reactive, and highly performant gateway solution built for the cloud.
• Routes, Predicates, and Filters: These are the core building blocks for configuring gateway behavior. You define what to match (predicates) and how to modify it (filters).
• Key Implementations:
  • Routing: Use Path predicates and a load-balanced URI (lb://service-name) to direct traffic.
  • Transformation: Use filters like StripPrefix, RewritePath, and AddRequestHeader to adapt requests.
  • Rate Limiting: Use the RequestRateLimiter filter with Redis and a custom KeyResolver to protect your services.

Next Up

Our gateway can now route, transform, and protect our services. But what happens if the order-service goes down? The gateway will try to route requests to it, and they will fail. If enough requests are failing and tying up resources, this could bring down the gateway itself! This is known as a cascading failure.

In our next lesson, we will tackle this problem by learning to implement the Circuit Breaker pattern with a fallback mechanism using Resilience4j to prevent cascading failures.