RestClient in Spring Boot 3: The Modern HTTP Client Guide

If you’ve been building Spring Boot applications for a while, you’ve probably used RestTemplate. It was the go-to synchronous HTTP client for years. But let’s be honest: RestTemplate is a legacy beast. It’s bloated, callback-heavy, and its error handling is a nightmare in production. I’ve lost count of how many times I’ve seen teams struggle with RestTemplate’s non-intuitive exception hierarchy or its tight coupling to the old Apache HttpClient.

Enter RestClient, introduced in Spring Framework 6.1 (Spring Boot 3.2). It’s the HTTP client Spring should have had from the start. RestClient is a synchronous, fluent, and immutable client that borrows the best ideas from WebClient (reactive) but keeps things simple for blocking calls. It’s not just a facelift—it’s a complete rethinking of how we make HTTP requests in Spring.

In this guide, I’ll walk you through everything you need to know: from basic usage to advanced patterns, error handling, testing, and migration from RestTemplate. I’ll also share war stories from production where RestClient saved the day—or where it could have if we’d used it sooner. By the end, you’ll never want to touch RestTemplate again.

Why RestClient? The End of RestTemplate

RestTemplate has been deprecated since Spring 5.0, yet many teams still cling to it. I get it—migration is painful. But RestClient is not just a new coat of paint; it’s a fundamentally better design. Here’s why:

1. Fluent API: RestClient uses a builder pattern that’s intuitive. No more chaining exchange() with anonymous classes.
2. Immutability: Once built, RestClient is thread-safe and immutable. No accidental state mutation.
3. Better Error Handling: RestClient provides onStatus and defaultStatusHandler to handle HTTP statuses cleanly. No more catching HttpClientErrorException and parsing the response body manually.
4. Reactive Integration: RestClient can be used alongside WebClient, sharing the same infrastructure.
5. Testability: RestClient works seamlessly with MockRestServiceServer, making unit tests a breeze.

Let’s see a quick comparison. RestTemplate code to make a GET request and parse JSON:

``java // Old RestTemplate ResponseEntity<List<Payment>> response = restTemplate.exchange( "https://api.example.com/payments", HttpMethod.GET, null, new ParameterizedTypeReference<List<Payment>>() {} ); ``

Now with RestClient:

``java // New RestClient List<Payment> payments = restClient.get() .uri("https://api.example.com/payments") .retrieve() .body(new ParameterizedTypeReference<>() {}); ``

Cleaner, right? And that’s just the beginning.

import org.springframework.web.client.RestClient;

public class RestClientBasicExample {
    public static void main(String[] args) {
        RestClient restClient = RestClient.create();

        String result = restClient.get()
                .uri("https://api.example.com/health")
                .retrieve()
                .body(String.class);

        System.out.println("Health check: " + result);
    }
}

Building and Configuring RestClient

A well-configured RestClient is crucial for production. Here’s how to set it up properly.

Basic Builder

``java RestClient restClient = RestClient.builder() .baseUrl("https://api.example.com") .defaultHeader("Authorization", "Bearer " + token) .defaultHeader("Accept", "application/json") .build(); ``

Timeouts – Never skip these. Use a custom ClientHttpRequestFactory like HttpComponentsClientHttpRequestFactory (Apache HttpClient) or JdkClientHttpRequestFactory (Java 11+).

```java import org.apache.hc.client5.http.impl.classic.HttpClients; import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager; import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;

PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager(); connectionManager.setMaxTotal(100); connectionManager.setDefaultMaxPerRoute(20);

HttpComponentsClientHttpRequestFactory requestFactory = new HttpComponentsClientHttpRequestFactory( HttpClients.custom() .setConnectionManager(connectionManager) .build() ); requestFactory.setConnectTimeout(5000); requestFactory.setReadTimeout(10000);

RestClient restClient = RestClient.builder() .requestFactory(requestFactory) .build(); ```

Error Handling – Use onStatus for specific HTTP statuses and defaultStatusHandler for a catch-all.

``java restClient.get() .uri("/payments/{id}", paymentId) .retrieve() .onStatus(status -> status.value() == 404, (request, response) -> { throw new PaymentNotFoundException("Payment not found: " + paymentId); }) .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> { throw new ClientException(response.getStatusText()); }) .body(Payment.class); ``

Interceptors – Great for logging, retries, or adding correlation IDs.

```java import org.springframework.http.client.ClientHttpRequestInterceptor;

ClientHttpRequestInterceptor loggingInterceptor = (request, body, execution) -> { System.out.println("Request: " + request.getMethod() + " " + request.getURI()); return execution.execute(request, body); };

RestClient restClient = RestClient.builder() .requestInterceptor(loggingInterceptor) .build(); ```

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.web.client.RestClient;

@Configuration
public class RestClientConfig {

    @Bean
    public RestClient paymentServiceClient() {
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory();
        factory.setConnectTimeout(5000);
        factory.setReadTimeout(10000);

        return RestClient.builder()
                .baseUrl("https://payments.example.com")
                .requestFactory(factory)
                .defaultHeader("Accept", "application/json")
                .build();
    }
}

Making Requests: GET, POST, PUT, DELETE

RestClient’s fluent API makes all HTTP methods straightforward. Let's cover the common patterns.

GET – Retrieve a resource.

``java Payment payment = restClient.get() .uri("/payments/{id}", paymentId) .retrieve() .body(Payment.class); ``

For a list with headers:

``java ResponseEntity<List<Payment>> response = restClient.get() .uri("/payments?status={status}", "completed") .retrieve() .toEntity(new ParameterizedTypeReference<>() {}); ``

POST – Create a resource.

``java Payment newPayment = new Payment(amount, currency); Payment created = restClient.post() .uri("/payments") .body(newPayment) .retrieve() .body(Payment.class); ``

PUT – Update a resource.

``java Payment updatedPayment = new Payment(amount, currency); restClient.put() .uri("/payments/{id}", paymentId) .body(updatedPayment) .retrieve() .toBodilessEntity(); ``

DELETE – Remove a resource.

``java restClient.delete() .uri("/payments/{id}", paymentId) .retrieve() .toBodilessEntity(); ``

Exchange – For full control over the response (e.g., to read headers).

``java String etag = restClient.get() .uri("/payments/{id}", paymentId) .exchange((request, response) -> { if (response.getStatusCode().is2xxSuccessful()) { return response.getHeaders().getETag(); } else { throw new RuntimeException("Failed"); } }); ``

Note: exchange gives you access to the raw ClientHttpResponse, but you must manage the response lifecycle (e.g., close the body).

import org.springframework.web.client.RestClient;
import org.springframework.http.ResponseEntity;

public class RestClientRequests {
    private final RestClient restClient;

    public RestClientRequests(RestClient restClient) {
        this.restClient = restClient;
    }

    public Payment getPayment(String id) {
        return restClient.get()
                .uri("/payments/{id}", id)
                .retrieve()
                .body(Payment.class);
    }

    public Payment createPayment(Payment payment) {
        return restClient.post()
                .uri("/payments")
                .body(payment)
                .retrieve()
                .body(Payment.class);
    }

    public void deletePayment(String id) {
        restClient.delete()
                .uri("/payments/{id}", id)
                .retrieve()
                .toBodilessEntity();
    }
}

Error Handling and Status Handlers

One of RestClient’s best features is its declarative error handling. You can handle specific status codes or ranges without messy try-catch blocks.

Basic Error Handling

By default, RestClient throws RestClientException for 4xx and 5xx responses. But you can customize this.

``java Payment payment = restClient.get() .uri("/payments/{id}", id) .retrieve() .onStatus(status -> status.value() == 404, (request, response) -> { throw new PaymentNotFoundException(); }) .onStatus(HttpStatusCode::is5xxServerError, (request, response) -> { throw new ServiceUnavailableException(); }) .body(Payment.class); ``

Default Status Handler

You can set a default handler at the builder level:

``java RestClient restClient = RestClient.builder() .defaultStatusHandler(HttpStatusCode::isError, (request, response) -> { throw new CustomHttpException(response.getStatusCode(), response.getStatusText()); }) .build(); ``

Reading Error Response Body

Sometimes you need the error body. Use onStatus with a custom extractor:

``java .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> { String errorBody = new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8); throw new ClientException(response.getStatusCode(), errorBody); }) ``

Retry After

For 429 Too Many Requests, you can retry after a delay:

``java .onStatus(status -> status.value() == 429, (request, response) -> { String retryAfter = response.getHeaders().getFirst("Retry-After"); throw new RateLimitExceededException(retryAfter); }) ``

Warning: Avoid using onStatus for every possible status code. Keep it maintainable by grouping statuses into ranges.

import org.springframework.web.client.RestClient;
import org.springframework.http.HttpStatusCode;

public class RestClientErrorHandling {
    private final RestClient restClient;

    public RestClientErrorHandling(RestClient restClient) {
        this.restClient = restClient;
    }

    public Payment getPaymentSafe(String id) {
        return restClient.get()
                .uri("/payments/{id}", id)
                .retrieve()
                .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> {
                    throw new ClientException("Client error: " + response.getStatusCode());
                })
                .onStatus(HttpStatusCode::is5xxServerError, (request, response) -> {
                    throw new ServerException("Server error: " + response.getStatusCode());
                })
                .body(Payment.class);
    }
}

Testing RestClient with MockRestServiceServer

Testing HTTP clients is critical. Spring provides MockRestServiceServer for mocking RestClient calls without hitting real endpoints.

Setup

```java import org.springframework.test.web.client.MockRestServiceServer; import static org.springframework.test.web.client.match.MockRestRequestMatchers.; import static org.springframework.test.web.client.response.MockRestResponseCreators.;

@ExtendWith(MockitoExtension.class) class PaymentServiceTest {

private MockRestServiceServer mockServer; private PaymentService paymentService;

@BeforeEach void setUp() { RestClient restClient = RestClient.builder() .baseUrl("https://api.example.com") .build(); mockServer = MockRestServiceServer.bindTo(restClient).build(); paymentService = new PaymentService(restClient); } ```

Test a Successful GET

```java @Test void shouldReturnPaymentWhenFound() { String json = "{\"id\":\"123\",\"amount\":100.0}"; mockServer.expect(requestTo("/payments/123")) .andExpect(method(HttpMethod.GET)) .andRespond(withSuccess(json, MediaType.APPLICATION_JSON));

Payment payment = paymentService.getPayment("123");

assertEquals("123", payment.id()); assertEquals(100.0, payment.amount()); } ```

Test Error Handling

```java @Test void shouldThrowNotFoundWhen404() { mockServer.expect(requestTo("/payments/999")) .andRespond(withStatus(HttpStatus.NOT_FOUND));

assertThrows(PaymentNotFoundException.class, () -> { paymentService.getPayment("999"); }); } ```

Test Timeout

You can simulate timeouts with a custom response creator:

``java mockServer.expect(requestTo("/payments/123")) .andRespond(withSuccess().body("{\"id\":\"123\"}").throttle(10000)); // 10 sec delay ``

Important: MockRestServiceServer works with RestClient’s ClientHttpRequestFactory. If you use a custom factory, you may need to bind differently. See the docs for advanced scenarios.

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.test.web.client.MockRestServiceServer;
import org.springframework.web.client.RestClient;

import static org.springframework.test.web.client.match.MockRestRequestMatchers.method;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;
import static org.junit.jupiter.api.Assertions.*;

class PaymentServiceTest {

    private MockRestServiceServer mockServer;
    private PaymentService paymentService;

    @BeforeEach
    void setUp() {
        RestClient restClient = RestClient.builder()
                .baseUrl("https://api.example.com")
                .build();
        mockServer = MockRestServiceServer.bindTo(restClient).build();
        paymentService = new PaymentService(restClient);
    }

    @Test
    void shouldReturnPayment() {
        String json = "{\"id\":\"123\",\"amount\":100.0}";
        mockServer.expect(requestTo("/payments/123"))
                .andExpect(method(HttpMethod.GET))
                .andRespond(withSuccess(json, MediaType.APPLICATION_JSON));

        Payment payment = paymentService.getPayment("123");

        assertEquals("123", payment.id());
        assertEquals(100.0, payment.amount());
    }
}

What the Official Docs Won't Tell You

After using RestClient in production for over a year, here are the gotchas that the Spring docs gloss over.

1. RestClient.create() Uses JDK HttpClient with No Timeouts

RestClient.create() creates a client using JdkClientHttpRequestFactory (Java 11+). This factory has no default timeouts. In production, a downstream slow service will hang your threads indefinitely. Always use a custom factory with explicit timeouts.

2. onStatus Handlers Must Throw or Handle

If your onStatus handler doesn't throw an exception and doesn't consume the response body, RestClient will return null from body() or toEntity(). This leads to confusing NullPointerException. The official docs mention this, but it’s easy to miss. My rule: always throw a custom exception in onStatus.

3. MockRestServiceServer with Custom Request Factory

If you configure a custom ClientHttpRequestFactory (e.g., Apache HttpClient), MockRestServiceServer.bindTo(restClient) might not work because it uses the default SimpleClientHttpRequestFactory. You need to bind to the underlying ClientHttpRequestFactory or use bindTo(restClient).ignoreExpectOrder(true). See the test section for workarounds.

4. Exchange vs Retrieve: Memory Leak Risk

When using exchange(), you must close the response body. If you don't, the underlying HTTP connection may not be released. The retrieve() method handles this automatically. Only use exchange when you need low-level control, and always close the body in a finally block.

5. Default Headers Are Not Merged with Request Headers

If you set a default header (e.g., Authorization) in the builder, and then set the same header on a specific request, the request header overrides the default. This is consistent with HTTP semantics, but it surprises many developers. If you want to merge, you need to do it manually.

6. RestClient Is Not a Drop-in Replacement for RestTemplate

While you can wrap a RestTemplate with RestClient.builder(restTemplate), the resulting RestClient inherits RestTemplate's quirks, like its exception hierarchy. For a clean migration, build a new RestClient from scratch.

// Gotcha 1: No timeouts with create()
RestClient badClient = RestClient.create(); // No timeouts!

// Gotcha 2: onStatus must throw
restClient.get()
    .uri("/test")
    .retrieve()
    .onStatus(HttpStatusCode::is4xxClientError, (req, resp) -> {
        // This doesn't throw -> body() returns null
    })
    .body(String.class); // Might return null

// Gotcha 5: Default header override
RestClient client = RestClient.builder()
    .defaultHeader("Authorization", "Bearer default")
    .build();
client.get()
    .uri("/test")
    .header("Authorization", "Bearer override") // overrides default
    .retrieve();

Migrating from RestTemplate to RestClient

If you have an existing codebase with RestTemplate, you don't need to rewrite everything overnight. Here’s a pragmatic migration strategy.

Step 1: Wrap RestTemplate

You can create a RestClient that delegates to an existing RestTemplate:

``java RestTemplate restTemplate = new RestTemplate(); RestClient restClient = RestClient.builder(restTemplate).build(); ``

This gives you the fluent API while keeping the old RestTemplate configuration. But this is a stepping stone—you still have RestTemplate under the hood.

Step 2: Replace Calls Incrementally

Start with the most critical or simplest endpoints. Replace restTemplate.getForObject() with restClient.get().retrieve().body(). Keep the old code until you’ve tested the new one.

Step 3: Migrate Error Handling

RestTemplate throws RestClientException subclasses like HttpClientErrorException. RestClient uses onStatus. You can create a compatibility layer:

``java restClient.get() .uri(url) .retrieve() .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> { throw new HttpClientErrorException(response.getStatusCode(), response.getStatusText()); }) .body(String.class); ``

Step 4: Remove RestTemplate Eventually

Once all calls are migrated, remove the RestTemplate bean. This may break other code that depends on it, so do it in a separate release.

Common Pitfalls

• URI Template Variables: RestTemplate uses UriTemplateHandler, RestClient uses uri(String, Object...). They are compatible, but check edge cases with encoded characters.
• Exchange vs retrieve: restTemplate.exchange() becomes restClient.get().retrieve().toEntity(). For full control, use exchange().
• Interceptors: RestTemplate’s ClientHttpRequestInterceptor works with RestClient. You can reuse them.

When Not to Migrate

If your app is short-lived or RestTemplate usage is minimal, migration may not be worth it. But for long-term projects, RestClient is the future.

// Before: RestTemplate
RestTemplate restTemplate = new RestTemplate();
String result = restTemplate.getForObject("https://api.example.com/data", String.class);

// After: RestClient (wrapping existing RestTemplate)
RestClient restClient = RestClient.builder(restTemplate).build();
String result = restClient.get()
        .uri("https://api.example.com/data")
        .retrieve()
        .body(String.class);

// Eventually: new RestClient without RestTemplate
RestClient newClient = RestClient.builder()
        .baseUrl("https://api.example.com")
        .build();
String result = newClient.get()
        .uri("/data")
        .retrieve()
        .body(String.class);