API Rate Limiting using Resilience4J & Spring Boot

How API rate limiting works, why fixed windows fail under bursts, and how to implement a sliding-window rate limiter with Resilience4J in Spring Boot, tested with JMeter.

API Rate Limiting using Resilience4J & Spring Boot

Introduction

In this blog, we’ll dive into the critical concept of API Rate Limiting and see how to implement a robust solution using Resilience4J in a Spring Boot application.

We will cover:

  • What API Rate Limiting is.
  • How the basic Fixed Window algorithm fails (the bursting issue).
  • How the Sliding Window algorithm, used by Resilience4J, solves the problem.
  • Implementing and configuring rate limiting in a Spring Boot REST API.
  • Testing the solution using JMeter.

What is API Rate Limiting?

API Rate Limiting is a defensive mechanism used to restrict the number of client requests an API will process within a specified time duration.

For example, a typical policy might allow 5 requests per every 10 seconds from a single user. Any requests that exceed this threshold are instantly rejected with an HTTP 429 Too Many Requests status code.

This practice is essential for:

  1. System Stability: Preventing sudden spikes of traffic from overwhelming your backend services.
  2. Abuse Prevention: Protecting against Distributed Denial of Service (DDoS) attacks.
  3. Fair Usage: Ensuring all consumers get a consistent quality of service.

Fixed Window vs. Sliding Window

Understanding the algorithm is key to effective rate limiting.

The Fixed Window Issue

The Fixed Window algorithm is the simplest approach. It divides the timeline into fixed, non-overlapping intervals (e.g., 60 seconds). All requests within that interval count toward the limit.

The major flaw is the “blasting” or “edge-case” problem.

Time Action Result
Window 1 (Second 59) User sends 5 requests (Limit is 5 per 60s) Processed.
Window 2 (Second 01) User sends 5 more requests Processed, as the limit just reset.

In this scenario, your API processed 10 requests in a span of just two seconds across the boundary. This heavy burst of traffic can still lead to momentary overload, even though the rate limit wasn’t technically violated in either window.

The Sliding Window Solution

The Sliding Window algorithm solves the blasting problem by providing a much smoother enforcement. It works by looking at a rolling window of time.

Instead of fixed buckets, the system maintains a log of timestamps for all successful requests. When a new request arrives, it only considers the requests that occurred within the past window duration (e.g., the last 10 seconds).

  • It checks the request count in the immediately preceding time window.
  • If the count is less than the limit, the request is processed, and its timestamp is added to the log.

This ensures that the number of requests in any rolling window never exceeds the configured limit, eliminating the boundary spikes. Resilience4J uses this superior algorithm for its rate limiting implementation.


Implementing Rate Limiting in Spring Boot

Let’s put this into practice in a Spring Boot application.

1. Adding Dependencies

We need the core web starter, the Resilience4J library, and the AOP starter to enable the annotation-based configuration.

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>io.github.resilience4j</groupId>
        <artifactId>resilience4j-spring-boot3</artifactId>
        <version>2.2.0</version> </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-aop</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>
  1. Creating a Rate-Limited Endpoint We create a simple REST controller and apply the @RateLimiter annotation. We also include a fallbackMethod to provide a clean response when the limit is reached.
@RestController
@RequestMapping("/api")
public class RateLimitedController {

    // Applies the rate limiter configuration named "test-api"
    @GetMapping("/hello")
    @RateLimiter(name = "test-api", fallbackMethod = "fallbackSayHello")
    public String sayHello() {
        // Simulating some processing time
        return "Hello! Request successfully processed.";
    }

    // Fallback method executed when the limit is hit
    // It accepts a Throwable parameter, which will be the RateLimiter exception
    public String fallbackSayHello(Throwable t) {
        // The service is protected, return a polite error
        return "Too Many Requests! Please try again later. (Error: " + t.getMessage() + ")";
    }
}
  1. Configuring the Rate Limiter The behavior of the test-api instance is defined in application.yml:
resilience4j.ratelimiter:
  instances:
    test-api:
      # Max number of requests allowed in the limit-refresh-period
      limit-for-period: 5
      # The size of the window (how often the limit resets/refreshes)
      limit-refresh-period: 15s 
      # How long a blocked thread can wait for a token before giving up.
      # Setting this to > 0s allows for "waiting" instead of immediate rejection.
      timeout-duration: 5s 
      # Register the rate limiter status in the Actuator health endpoint
      register-health-indicator: true 
management:
  endpoints:
    web:
      exposure:
        include: health, ratelimiters # Expose the ratelimiters endpoint
Configuration Key Description
limit-for-period The maximum number of requests allowed per window.
limit-refresh-period The duration of the sliding window.
timeout-duration The maximum time a thread waits to acquire a token before being rejected.

Testing the Rate Limiter using JMeter

With the application running, we can test our configuration (5 requests per 15 seconds) by simulating a spike in traffic using JMeter or any other load testing tool.

Testing Steps:

  1. Thread Group: Configure a Thread Group with the Number of Threads (Users) set to a value significantly higher than the limit (e.g., 50). Set the Ramp-up period to a low value (e.g., 1 second) to ensure all 50 requests hit the server nearly simultaneously.

  2. HTTP Request Sampler: Point the request to our endpoint: GET http://localhost:8080/api/hello.

  3. Run: Execute the test.

Expected Results:

  • The first 5 requests will be processed successfully, returning the status HTTP 200 OK and the message: “Hello! Request successfully processed.”

  • The remaining 45 requests will be blocked by the rate limiter. Due to our fallbackMethod being executed successfully, they will also return HTTP 200 OK, but with the message: “Too Many Requests! Please try again later. (Error: RateLimiter ’test-api’ does not permit further calls)”

Note: If you removed the fallbackMethod, the blocked requests would return the standard 429 Too Many Requests HTTP status code. The use of the fallback provides a more graceful and user-friendly experience.

Conclusion

Rate limiting is not just an optional feature; it’s a fundamental requirement for building resilient and scalable microservices. By leveraging the Sliding Window algorithm through Resilience4J and Spring Boot’s seamless configuration, you can effectively protect your services from sudden traffic spikes and guarantee a consistent user experience.

0 Tap to clap (up to 50)
Anbumani Mailathipathy

Lead Software Engineer and Cloud Architect with 13+ years in Java, Spring Boot and cloud, specialising in AI automation. Building with Claude at CreativeStudio14.

Comments

    Leave a comment

    Comments are moderated before they appear.