A Guide to RestClient in Spring Boot

In Spring Boot applications, communication with external services through REST APIs is common. Traditionally, this was achieved using RestTemplate, but it is now deprecated as of Spring Framework 6.1 and Spring Boot 3.2. The new RestClient API has been introduced as its modern, fluent, and flexible alternative for making HTTP requests.

What is RestClient?

RestClient is a modern HTTP client introduced in Spring Framework 6.1. It provides a fluent, builder-based API for sending synchronous and asynchronous HTTP requests with cleaner syntax and improved readability. It supports features like request customization, status-based error handling, interceptors, and HTTP/2 communication.

Key Features of RestClient

1. Fluent API Design

The fluent API allows developers to build requests using method chaining, improving code clarity and reducing boilerplate.

Example:

Explanation:

• get(): defines the HTTP method.
• uri(): specifies the target URL.
• retrieve(): executes the request.
• body(String.class): extracts the response as a String.

2. Synchronous and Asynchronous Requests

Synchronous Example:

This blocks the thread until a response is received.

Asynchronous Example:

RestClient integrates with reactive and asynchronous types like CompletableFuture or Mono.

3. Error and Status Code Handling

RestClient provides built-in support for handling errors based on HTTP status codes using the onStatus() method.

Example:

Explanation:

• onStatus() handles responses based on HTTP status codes.
• HttpStatus::is4xxClientError handles client-side errors.
• HttpStatus::is5xxServerError handles server-side errors.

4. Request Customization

Developers can add headers, query parameters, and path variables directly through the fluent builder methods.

Explanation:

• header(): adds custom HTTP headers.
• queryParam(): appends query parameters.
• {id}: path variable replaced dynamically.

5. Sending and Receiving Request Bodies

For methods like POST or PUT, RestClient supports serializing Java objects to JSON automatically (using Jackson).

Example – Sending JSON Request:

Example – Receiving as Object:

6. Configuring the Timeout

You can configure connection or read timeouts by customizing the underlying Java HttpClient.

This configuration ensures that requests fail gracefully if the connection cannot be established within 5 seconds.

7. Interceptors and Filters

Interceptors can modify requests or responses, ideal for logging or authentication.

This interceptor logs the URI before sending the request.

8. Built-in Support for the HTTP/2

RestClient supports HTTP/2 when used with HttpClient from Java 11+.

HTTP/2 improves communication speed and efficiency in distributed systems.

Setting up RestClient in Spring Boot

To use RestClient, you need Spring Boot 3.2 or later. Add the following Maven dependency.

Ensure your Spring Boot version is 3.2 or higher, as RestClient is part of Spring Framework 6.1+.

Creating a RestClient Bean

There are two ways to create and configure a RestClient instance in a Spring Boot application.

1. Creating RestClient as a Spring Bean (Recommended)

Define it inside a @Configuration class using RestClientBuilder.

Explanation:

• This approach allows Spring to manage the RestClient lifecycle.
• It supports dependency injection and centralized configuration.

2. Manually Creating the RestCleint

You can also create a standalone instance without Spring’s dependency injection.

Explanation:

• Use this when you need a lightweight or isolated instance.
• Less flexible for configuration sharing across the application.

Using RestClient in a Service Class

Example – GET Request

Example – POST Request