Setting a Request Timeout for a Spring REST API

1. Overview

In this tutorial, we’ll explore a few possible ways to implement request timeouts for a Spring REST API.

We’ll discuss the benefits and drawbacks of each. Request timeouts are useful for preventing a poor user experience, especially if there is an alternative that we can default to when a resource is taking too long. This design pattern is called the Circuit Breaker pattern, but we won’t elaborate on that here.

2. @Transactional Timeouts

One way we can implement a request timeout on database calls is to take advantage of Spring’s @Transactional annotation. It has a timeout property that we can set. The default value for this property is -1, which is equivalent to not having any timeout at all. For external configuration of the timeout value, a different property – timeoutString – must be used instead.

For example, let’s assume we set this timeout to 30. If the execution time of the annotated method exceeds this number of seconds, an exception would be thrown. This might be useful for rolling back long-running database queries.

To see this in action, let’s write a very simple JPA repository layer that will represent an external service that takes too long to complete and causes a timeout to occur. This JpaRepository extension has a time-costly method in it:

public interface BookRepository extends JpaRepository<Book, String> {

    default int wasteTime() {
        int i = Integer.MIN_VALUE;
        while(i < Integer.MAX_VALUE) {
            i++;
        }
        return i;
    }
}

If we invoke our wasteTime() method while inside of a transaction with a timeout of 1 second, the timeout will elapse before the method finishes executing:

@GetMapping("/author/transactional")
@Transactional(timeout = 1)
public String getWithTransactionTimeout(@RequestParam String title) {
    bookRepository.wasteTime();
    return bookRepository.findById(title)
      .map(Book::getAuthor)
      .orElse("No book found for this title.");
}

Calling this endpoint results in a 500 HTTP error, which we could transform into a more meaningful response. It also requires very little setup to implement.

However, there are a few drawbacks to this timeout solution.

Firstly, it is dependent on having a database with Spring-managed transactions. It also is not globally applicable to a project since the annotation must be present on each method or class that needs it. It also doesn’t allow sub-second precision. Finally, it doesn’t cut the request short when the timeout is reached, so the requesting entity still has to wait the full amount of time.

Let’s consider some other options.

3. Resilience4j TimeLimiter

Resilience4j is a library primarily dedicated to managing fault-tolerance for remote communications. Its TimeLimiter module is what we are interested in here.

First, we must include the resilience4j-timelimiter dependency in our project:

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-timelimiter</artifactId>
    <version>1.6.1</version>
</dependency>

Next, let’s define a simple TimeLimiter that has a timeout duration of 500 milliseconds:

private TimeLimiter ourTimeLimiter = TimeLimiter.of(TimeLimiterConfig.custom()
  .timeoutDuration(Duration.ofMillis(500)).build());

This could easily be externally configured.

We can use our TimeLimiter to wrap the same logic that our @Transactional example used:

@GetMapping("/author/resilience4j")
public Callable<String> getWithResilience4jTimeLimiter(@RequestParam String title) {
    return TimeLimiter.decorateFutureSupplier(ourTimeLimiter, () ->
      CompletableFuture.supplyAsync(() -> {
        bookRepository.wasteTime();
        return bookRepository.findById(title)
          .map(Book::getAuthor)
          .orElse("No book found for this title.");
    }));
}

The TimeLimiter offers several benefits over the @Transactional solution. Namely, it supports sub-second precision and immediate notification of the timeout response. However, it still must be manually included in all endpoints that require a timeout, it requires some lengthy wrapping code, and the error it produces is still a generic 500 HTTP error. Also, it requires returning a Callable<String> instead of a raw String.

The TimeLimiter comprises only a subset of features from Resilience4j and interfaces nicely with a Circuit Breaker pattern.

4. Spring MVC request-timeout

Spring provides us with a property called spring.mvc.async.request-timeout. This property allows us to define a request timeout with millisecond precision.

Let’s define the property with a 750-millisecond timeout:

spring.mvc.async.request-timeout=750

This property is global and externally configurable, but like the TimeLimiter solution, it only applies to endpoints that return a Callable. Let’s define an endpoint that is similar to the TimeLimiter example, but without needing to wrap the logic in Futures or supplying a TimeLimiter:

@GetMapping("/author/mvc-request-timeout")
public Callable<String> getWithMvcRequestTimeout(@RequestParam String title) {
    return () -> {
        bookRepository.wasteTime();
        return bookRepository.findById(title)
          .map(Book::getAuthor)
          .orElse("No book found for this title.");
    };
}

We can see that the code is less verbose, and the configuration is automatically implemented by Spring when we define the application property. The response is returned immediately once the timeout has been reached, and it even returns a more descriptive 503 HTTP error instead of a generic 500. Also, every endpoint in our project will inherit this timeout configuration automatically.

Let’s consider another option that will allow us to define timeouts with a little more granularity.

5. WebClient Timeouts

Rather than setting a timeout for an entire endpoint, perhaps we want to simply have a timeout for a single external call. WebClient is Spring’s reactive web client and allows us to configure a response timeout.

It is also possible to configure timeouts on Spring’s older RestTemplate object. However, most developers now prefer WebClient over RestTemplate.

To use WebClient, we must first add Spring’s WebFlux dependency to our project:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <version>2.4.2</version>
</dependency>

Let’s define a WebClient with a response timeout of 250 milliseconds that we can use to call ourselves via localhost in its base URL:

@Bean
public WebClient webClient() {
    return WebClient.builder()
      .baseUrl("http://localhost:8080")
      .clientConnector(new ReactorClientHttpConnector(
        HttpClient.create().responseTimeout(Duration.ofMillis(250))
      ))
      .build();
}

Clearly, we could easily configure this timeout value externally. We could also configure the base URL externally, as well as several other optional properties.

Now we can inject our WebClient into our controller and use it to call our own /transactional endpoint, which still has a timeout of 1 second. Since we configured our WebClient to timeout in 250 milliseconds, we should see it fail much faster than 1 second.

Here is our new endpoint:

@GetMapping("/author/webclient")
public String getWithWebClient(@RequestParam String title) {
    return webClient.get()
      .uri(uriBuilder -> uriBuilder
        .path("/author/transactional")
        .queryParam("title", title)
        .build())
      .retrieve()
      .bodyToMono(String.class)
      .block();
}

After calling this endpoint, we see that we do receive the WebClient‘s timeout in the form of a 500 HTTP error response. We can also check the logs to see the downstream @Transactional timeout. But of course, its timeout would have been printed remotely if we called an external service instead of localhost.

Configuring different request timeouts for different backend services may be necessary and is possible with this solution. Also, the Mono or Flux response publishers returned by WebClient contain plenty of error handling methods for handling the generic timeout error response.

6. Conclusion

We’ve just explored several different solutions for implementing a request timeout in this article. There are several factors to consider when deciding which one to use.

If we want to place a timeout on our database requests, we might want to use Spring’s @Transactional method and its timeout property. If we are trying to integrate with a broader Circuit Breaker pattern, using Resilience4j’s TimeLimiter would make sense. Using the Spring MVC request-timeout property is best for setting a global timeout for all requests, but we can easily define more granular timeouts per resource with WebClient.

For a working example of all of these solutions, the code is ready and runnable out of the box over on GitHub.