View source for RestTemplateBuilder: A Modern Approach to HTTP Clients in Spring Boot

<span id="resttemplatebuilder-a-modern-approach-to-http-clients-in-spring-boot"></span>
== RestTemplateBuilder: A Modern Approach to HTTP Clients in Spring Boot ==

In the landscape of Java’s Spring Boot framework, making HTTP requests to external services is a cornerstone of building interconnected microservices and applications. While the classic <code>RestTemplate</code> has long been the go-to tool for this task, Spring Boot offers a more powerful and elegant solution: the <code>RestTemplateBuilder</code>. This builder utility simplifies the configuration and creation of <code>RestTemplate</code> instances, promoting cleaner code and centralized management of HTTP client settings.

<span id="what-is-resttemplatebuilder"></span>
=== What is RestTemplateBuilder? ===

At its core, <code>RestTemplateBuilder</code> is a factory for creating and customizing <code>RestTemplate</code> objects. In a Spring Boot application, a <code>RestTemplateBuilder</code> bean is automatically configured and made available for injection, carrying with it sensible defaults and the ability to be further tailored to specific needs. This eliminates the need for manual and often verbose setup of <code>RestTemplate</code>, allowing developers to focus on the business logic of their applications.

<span id="the-advantages-of-using-resttemplatebuilder"></span>
=== The Advantages of Using RestTemplateBuilder ===

Using <code>RestTemplateBuilder</code> offers several distinct advantages over creating <code>RestTemplate</code> instances directly:

* '''Simplified Configuration:''' The builder provides a fluent API for setting various properties of the <code>RestTemplate</code>, such as connection and read timeouts, message converters for handling different data formats (like JSON and XML), and interceptors for modifying requests and responses. This approach is more readable and less error-prone than manual configuration.
* '''Centralized Customization:''' <code>RestTemplateBuilder</code> encourages the centralization of <code>RestTemplate</code> configurations. By defining a <code>RestTemplate</code> bean using the builder in a configuration class, you can ensure that all parts of your application use a consistently configured HTTP client.
* '''Automatic Defaults:''' Spring Boot’s auto-configured <code>RestTemplateBuilder</code> comes with a pre-configured set of <code>HttpMessageConverter</code> instances, making it ready to handle common data types out of the box.
* '''Seamless Integration with Testing:''' Spring Boot provides excellent testing support for code that uses <code>RestTemplateBuilder</code>, allowing for the easy mocking of external services in your tests.

<span id="practical-usage-and-common-configurations"></span>
=== Practical Usage and Common Configurations ===

Getting started with <code>RestTemplateBuilder</code> is straightforward. You can inject it directly into your services or create a <code>RestTemplate</code> bean in a configuration class.

<span id="basic-instantiation"></span>
==== Basic Instantiation ====

Here’s a simple example of how to use <code>RestTemplateBuilder</code> to create a <code>RestTemplate</code> instance within a service:


<syntaxhighlight lang="java">import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

@Service
public class MyService {

    private final RestTemplate restTemplate;

    public MyService(RestTemplateBuilder restTemplateBuilder) {
        this.restTemplate = restTemplateBuilder.build();
    }

    // ... methods that use restTemplate
}</syntaxhighlight>
For application-wide use, it’s best practice to define a <code>RestTemplate</code> bean in a configuration class:


<syntaxhighlight lang="java">import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class AppConfig {

    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder.build();
    }
}</syntaxhighlight>
<span id="common-configuration-examples"></span>
==== Common Configuration Examples ====

The true power of <code>RestTemplateBuilder</code> lies in its ability to easily configure various aspects of the <code>RestTemplate</code>.

'''Setting Timeouts:'''

To prevent your application from being blocked by unresponsive services, it’s crucial to set connection and read timeouts.


<syntaxhighlight lang="java">import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;
import java.time.Duration;

@Configuration
public class AppConfig {

    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder
                .setConnectTimeout(Duration.ofSeconds(5))
                .setReadTimeout(Duration.ofSeconds(5))
                .build();
    }
}</syntaxhighlight>
'''Adding a Root URI:'''

If you frequently make requests to the same base URL, you can set a root URI to simplify your request calls.


<syntaxhighlight lang="java">import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class AppConfig {

    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder
                .rootUri("https://api.example.com")
                .build();
    }
}</syntaxhighlight>
Now, when you use this <code>RestTemplate</code>, you only need to provide the path relative to the root URI: <code>restTemplate.getForObject(&quot;/users/{id}&quot;, User.class, 1L);</code>

'''Configuring Basic Authentication:'''

For services that require basic authentication, you can easily configure the credentials.


<syntaxhighlight lang="java">import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class AppConfig {

    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder
                .basicAuthentication("username", "password")
                .build();
    }
}</syntaxhighlight>
<span id="advanced-customization-with-resttemplatecustomizer"></span>
=== Advanced Customization with <code>RestTemplateCustomizer</code> ===

For more advanced or application-wide customizations, Spring Boot offers the <code>RestTemplateCustomizer</code> interface. You can create beans of this type to apply customizations to the auto-configured <code>RestTemplateBuilder</code>. This is particularly useful for adding interceptors or message converters that should be applied globally.

For example, to add a custom logging interceptor to all <code>RestTemplate</code> instances created by the builder:


<syntaxhighlight lang="java">import org.springframework.boot.web.client.RestTemplateCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.ClientHttpRequestInterceptor;

@Configuration
public class RestTemplateCustomizationConfig {

    @Bean
    public RestTemplateCustomizer restTemplateCustomizer() {
        return restTemplate -> {
            restTemplate.getInterceptors().add(loggingInterceptor());
        };
    }

    @Bean
    public ClientHttpRequestInterceptor loggingInterceptor() {
        return (request, body, execution) -> {
            // Log request details
            return execution.execute(request, body);
        };
    }
}</syntaxhighlight>
<span id="testing-with-resttemplatebuilder"></span>
=== Testing with <code>RestTemplateBuilder</code> ===

Spring Boot’s testing framework seamlessly integrates with <code>RestTemplateBuilder</code>. The <code>@RestClientTest</code> annotation is a powerful tool for testing code that makes HTTP calls. It auto-configures a <code>MockRestServiceServer</code> which allows you to define mock responses for specific requests.

Here’s an example of how to test a service that uses a <code>RestTemplate</code> created by a <code>RestTemplateBuilder</code>:


<syntaxhighlight lang="java">import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.client.RestClientTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.client.MockRestServiceServer;

import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;

@RestClientTest(MyService.class)
public class MyServiceTest {

    @Autowired
    private MyService myService;

    @Autowired
    private MockRestServiceServer server;

    @Test
    void testGetUser() {
        String userJson = "{\"id\": 1, \"name\": \"John Doe\"}";

        this.server.expect(requestTo("/users/1"))
                .andRespond(withSuccess(userJson, MediaType.APPLICATION_JSON));

        // Call the service method that uses RestTemplate
        // and assert the result
    }
}</syntaxhighlight>
In this test, <code>@RestClientTest</code> focuses on the <code>MyService</code> and provides a <code>MockRestServiceServer</code>. We then set an expectation on the server that a request to <code>/users/1</code> will be made and should be responded to with a success status and a predefined JSON body. This allows for isolated and reliable testing of your service’s logic without making actual network calls.

In conclusion, <code>RestTemplateBuilder</code> is an indispensable tool in the modern Spring Boot developer’s arsenal. It promotes best practices for creating and managing <code>RestTemplate</code> instances, leading to more robust, maintainable, and easily testable applications. By leveraging the power of the builder and its associated testing utilities, you can confidently integrate your Spring Boot applications with the vast world of external RESTful services.