Spring gives you several ways to call a remote REST endpoint, and the names are easy to confuse. This article compares the three clients most teams ask about: RestClient, WebClient and RestTemplate. It was written for Spring Boot 4.1.2.
The short answer, taken from the official Spring Boot and Spring Framework pages:
- Use
RestClientfor synchronous (imperative) code. It is the current choice for new blocking code. - Use
WebClientwhen you build a non-blocking, reactive application on Spring WebFlux. - Treat
RestTemplateas legacy. The Spring Framework reference describes it as "now deprecated in favor ofRestClient".
The Spring Framework reference also lists a fourth option, HTTP Service Clients: an annotated interface backed by a generated proxy. This article mentions it but does not compare it in depth, because the pages used here only name it. See the official REST Clients page for its details.
What each client is
The Spring Framework reference defines the three clients in one line each:
RestClient: a synchronous client with a fluent API.WebClient: a non-blocking, reactive client with a fluent API.RestTemplate: a synchronous client with a template method API, now deprecated in favor ofRestClient.
RestClient and WebClient look alike on purpose. The Spring Boot reference says that if you are not writing a reactive Spring WebFlux application, you can use RestClient instead of WebClient. It describes it as a similar functional API, but imperative rather than reactive.
RestTemplate is older and uses a different style: methods grouped by HTTP method, plus generalized exchange and execute methods for less frequent cases. The RestTemplate API page points readers to RestClient for a more modern synchronous API, and to WebClient for asynchronous and streaming scenarios.
Criteria used for the comparison
Each client is judged on the same six points. They are the ones that change your code and your operations most.
- Threading model: does a call block the calling thread or return a reactive type?
- API style: fluent builder chain or template methods?
- Project direction: where does the Spring team put new features?
- Configuration and sharing: how do you build it, and is it safe to share?
- Underlying HTTP library: what can you plug in?
- Spring Boot integration: what does Boot set up for you?
The next sections apply these criteria in turn. The summary table is in the section after that.
Threading model and API style
RestClient is synchronous. You chain a method such as get(), head(), post() or method(HttpMethod), add a URI, optionally headers and a body, then call retrieve(). For the body you call retrieve().body(Class), or retrieve().body(ParameterizedTypeReference) for generics such as lists. The call returns the converted object directly.
WebClient is non-blocking and reactive. It exposes the same kind of fluent chain (get(), post(), put(), patch(), delete(), options(), head(), method(HttpMethod)), but the result is a reactive type. In the Spring Boot example, retrieve().bodyToMono(Details.class) returns a Mono<Details>.
RestTemplate is synchronous with a template method API. It offers exchange overloads that take a URL, an HttpMethod, an optional HttpEntity and a response type, and return a ResponseEntity. It also offers execute, which takes a RequestCallback and a ResponseExtractor.
The practical consequence is simple. If your service method returns a plain object, RestClient fits. If it returns Mono, WebClient fits. Mixing them means you either block inside reactive code or wrap blocking calls, and the pages used for this article do not cover those workarounds. Check the Spring Framework reference before you try either.
A RestClient example
This class builds a RestClient with a base URL and returns the response body as a typed object. Every method used here is described on the official REST Clients page: RestClient.builder(), baseUrl, get(), uri with a URI template variable, retrieve() and body(Class).
Why a builder: it is where you set the base URL once, so each call only needs the path.
The Details record is a placeholder for your own response type. Replace https://example.org with your service.
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;
@Service
public class MyRestClientService {
public record Details(String name) {
}
private final RestClient restClient;
public MyRestClientService() {
this.restClient = RestClient.builder()
.baseUrl("https://example.org")
.build();
}
public Details someRestCall(String name) {
return this.restClient.get()
.uri("/{name}/details", name)
.retrieve()
.body(Details.class);
}
}
A WebClient example
This is the pattern from the Spring Boot reference. Boot creates and pre-configures a prototype WebClient.Builder bean, and the reference strongly advises you to inject it and build your WebClient from it.
Why inject the builder: Boot configures it to share HTTP resources and to reflect the codec setup in the same fashion as the server ones.
The Details record is again a placeholder. The method returns a Mono, so the caller decides how to subscribe or compose.
import reactor.core.publisher.Mono;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
@Service
public class MyService {
public record Details(String name) {
}
private final WebClient webClient;
public MyService(WebClient.Builder webClientBuilder) {
this.webClient = webClientBuilder.baseUrl("https://example.org").build();
}
public Mono<Details> someRestCall(String name) {
return this.webClient.get().uri("/{name}/details", name).retrieve().bodyToMono(Details.class);
}
}
Project direction
The RestTemplate API page states that RestTemplate and RestClient share the same infrastructure: request factories, request interceptors and initializers, message converters and more. Improvements to that shared infrastructure benefit both. However, it also says RestClient is the focus for new higher-level features.
That sentence is the main reason to move on from RestTemplate. Your existing code keeps working, but new capabilities are aimed at RestClient. For example, RestClient.builder() supports defaultVersion and apiVersionInserter for API versioning.
WebClient is not a replacement for either synchronous client. It is the reactive option, and the Spring Boot reference recommends it whenever Spring WebFlux is on the classpath.
Configuration, sharing and thread safety
The three clients handle configuration differently, and the differences matter in shared singletons.
RestClient offers RestClient.create() and RestClient.builder(). The builder can select the HTTP library through a request factory, configure message converters, set a baseUrl, set default headers, cookies, URI variables and API version, and register interceptors and request initializers. Once created, a RestClient is safe to use in multiple threads.
WebClient offers WebClient.create(), WebClient.create(String baseUrl) and WebClient.builder(). Builder options include defaultHeader, defaultCookie, defaultApiVersion, defaultRequest, filter, exchangeStrategies, clientConnector, apiVersionInserter, observationRegistry and observationConvention. Once built, a WebClient is immutable. You call mutate() to get a builder that copies its settings, then build a modified copy.
RestTemplate is typically used as a shared component, but its configuration does not support concurrent modification. Prepare it at startup. If you need different settings, create several instances at startup. They may share one ClientHttpRequestFactory so they share HTTP client resources.
In short, RestClient and WebClient are safe to share after construction by design. With RestTemplate you carry that discipline yourself.
Underlying HTTP library and Boot integration
RestClient is an abstraction over HTTP libraries. You choose one with requestFactory(...), for example new HttpComponentsClientHttpRequestFactory() in the official example. RestTemplate works the same way through a ClientHttpRequestFactory, with HttpURLConnection and Apache HttpComponents named as examples.
WebClient uses a ClientHttpConnector. WebClient.create() uses Reactor Netty by default. In Spring Boot, the connector is auto-detected from the classpath, in this order of preference:
- Reactor Netty
- Jetty RS client
- Apache HttpClient
- JDK HttpClient
The spring-boot-starter-webflux starter depends on io.projectreactor.netty:reactor-netty by default. To pick a connector globally, set spring.http.clients.reactive.connector, for example to jetty. To go further, declare your own ClientHttpConnector bean, or use ClientHttpConnectorBuilderCustomizer or a ClientHttpConnectorBuilder bean.
When the same technology serves both server and client, Boot shares HTTP resources between them. You can override resource configuration for Jetty and Reactor Netty with a custom ReactorResourceFactory or JettyResourceFactory bean, and it applies to both.
The Spring Boot reference documents the pre-configured WebClient.Builder bean in detail. The pages used for this article do not describe equivalent auto-configuration for RestClient or RestTemplate. Check the Spring Boot page Calling REST Services for your version before you rely on it.
Side-by-side summary
| Criterion | RestClient | WebClient | RestTemplate |
|---|---|---|---|
| Threading model | Synchronous | Non-blocking, reactive | Synchronous |
| API style | Fluent | Fluent, reactive types | Template methods |
| Direction | Focus for new higher-level features | Reactive option, recommended with WebFlux | Deprecated in favor of RestClient |
| After construction | Safe in multiple threads | Immutable, mutate() to copy |
Config not safe to modify concurrently |
| HTTP library | Request factory | ClientHttpConnector |
ClientHttpRequestFactory |
| Boot detail | See Boot page | Pre-configured WebClient.Builder bean, connector auto-detection |
See Boot page |
Which one to choose
Match the client to your situation rather than to a trend.
New blocking application (Spring MVC style). Choose RestClient. It is synchronous, has the fluent API, and is where new features land.
Reactive application on Spring WebFlux. Choose WebClient. The Spring Boot reference recommends it when WebFlux is on the classpath, and Boot gives you a pre-configured builder.
Streaming or asynchronous needs. Choose WebClient. The RestTemplate API page names the reactive WebClient for asynchronous and streaming scenarios.
Existing codebase full of RestTemplate. Keep it working, and write new calls with RestClient. Because both share request factories, interceptors, initializers and message converters, you can reuse that infrastructure when you move. Plan the migration gradually, since the deprecation is a direction and not a reason to rewrite everything at once.
Not sure and not reactive. Choose RestClient. The Spring Boot reference says the same: without a reactive WebFlux application, use it instead of WebClient.
Pitfalls to expect with WebClient
WebClient codecs limit in-memory buffering, and the default is 256KB. A larger response fails with org.springframework.core.io.buffer.DataBufferLimitException: Exceeded limit on max bytes to buffer. Raise it through the builder:
WebClient.builder().codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024)).build()
Reactor Netty HttpClient also takes part in global resources held in reactor.netty.http.HttpResources, including event loop threads and a connection pool. The reference calls this the recommended mode. Those resources stay active until the process exits. If your server can start or stop in-process, such as a Spring MVC application deployed as a WAR, declare a ReactorResourceFactory bean so Boot shuts them down when the ApplicationContext closes.
What we compared
- Threading model: blocking versus non-blocking reactive
- API style: fluent chain versus template methods
- Project direction: where new features are added
- Configuration and thread safety after construction
- Underlying HTTP library choice
- Spring Boot integration and auto-configuration
Recommendation
Use RestClient for new synchronous code, WebClient when you build a reactive Spring WebFlux application or need streaming and asynchronous calls, and keep RestTemplate only in existing code while you migrate to RestClient. If you are not on WebFlux, RestClient is the default choice.
Caveats
- RestTemplate is documented as deprecated in favor of RestClient, so new code on it adds migration work later.
- WebClient returns reactive types. Using it in a purely blocking application adds Reactor concepts to your code, and the official pages used here do not describe how to bridge the two.
- The Spring Boot reference documents the pre-configured WebClient.Builder bean in detail. Check the Calling REST Services page for your version to see what Boot configures for RestClient and RestTemplate.
- HTTP Service Clients (an annotated interface backed by a generated proxy) are not compared here. Read the official REST Clients page for them.
- Examples use a placeholder Details type and the placeholder host https://example.org. Replace both with your own.
Frequently asked questions
Is RestTemplate deprecated?
The Spring Framework REST Clients page describes RestTemplate as a synchronous client with a template method API, now deprecated in favor of RestClient.
Do I have to use WebClient with Spring Boot?
No. The Spring Boot reference recommends WebClient if Spring WebFlux is on your classpath. If you are not writing a reactive application, you can use RestClient instead.
Is RestClient thread safe?
Yes. The REST Clients page states that once created, a RestClient is safe to use in multiple threads.
Can RestClient and RestTemplate share configuration?
They share the same infrastructure: request factories, request interceptors and initializers, and message converters, according to the RestTemplate API page.
Which HTTP library does WebClient use in Spring Boot?
Boot auto-detects it in this order: Reactor Netty, Jetty RS client, Apache HttpClient, JDK HttpClient. You can override it with spring.http.clients.reactive.connector.
How do I change a WebClient after it is built?
You cannot modify it, because a built WebClient is immutable. Call mutate() to get a builder that copies its settings, then build a modified copy.
References
From Grokem: https://www.grokem.com/programming/apis-integrations/restclient-vs-webclient-vs-resttemplate-in-spring-boot-which-to-use








