By WebNest Studio Engineering Team
Spring Boot Tutorial
Calling REST APIs with RestClient
Modern applications constantly call other services: payment gateways, email providers, weather APIs, and your own microservices. Spring's RestClient, introduced in Spring Framework 6.1, is the recommended synchronous HTTP client for Spring MVC applications. It has a fluent API similar to WebClient but blocking, which pairs perfectly with virtual threads.
This lesson covers creating RestClient instances with Spring Boot's auto-configured builder, GET/POST/PUT/DELETE requests, path and query parameters, headers and authentication, reading responses and status codes, error handling, timeouts, logging interceptors, SSRF protection, and testing with MockRestServiceServer.
RestClient vs RestTemplate vs WebClient
RestTemplate is the classic client; it still works but is in maintenance mode and its many overloaded methods are awkward. WebClient is the reactive, non-blocking client for WebFlux applications. RestClient is the modern choice for everything else. It shares message converters and interceptors with the rest of Spring MVC and can be created from an existing RestTemplate configuration during migration.
The Auto-Configured Builder
In Spring Boot 4, HTTP client support has its own starter: add spring-boot-starter-restclient (the web starter alone no longer brings it). Spring Boot then provides a prototype RestClient.Builder bean already configured with the application's JSON mapper, HTTP client settings and any RestClientCustomizer beans. Inject the builder, set a base URL and default headers, and build one RestClient per remote service. Global timeouts and redirects are configured with spring.http.clients.* properties.
Making Requests
The chain is: method (get(), post()...) → uri(...) with templates and variables → optional headers, contentType, body → retrieve() → body(Type.class), toEntity(Type.class) (with status and headers) or toBodilessEntity(). For generic types such as lists use ParameterizedTypeReference. exchange(...) gives full manual control over the response.
Error Handling
By default retrieve() throws HttpClientErrorException for 4xx and HttpServerErrorException for 5xx responses. Use onStatus(predicate, handler) to translate specific statuses into your own exceptions — for example 404 into Optional.empty() or a ProductNotFoundException. Network failures and timeouts throw ResourceAccessException. Combine with retries (see the resilience lesson) for transient failures.
Timeouts and Security
Always set connect and read timeouts; without them, a hung remote service can block your threads indefinitely. When URLs come from users (webhooks, link previews), protect against SSRF with Spring Boot 4.1's InetAddressFilter, which blocks requests to internal network addresses.
Examples
A client for an external API built from the auto-configured builder
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-restclient</artifactId> <!-- new in Spring Boot 4 -->
</dependency>
# application.yml
spring:
http:
clients:
connect-timeout: 2s
read-timeout: 5s
github:
base-url: https://api.github.com
token: ${GITHUB_TOKEN}
public record GithubRepo(String name, @JsonProperty("stargazers_count") int stars, String language) {}
@Component
public class GithubClient {
private final RestClient client;
public GithubClient(RestClient.Builder builder,
@Value("${github.base-url}") String baseUrl,
@Value("${github.token}") String token) {
this.client = builder
.baseUrl(baseUrl)
.defaultHeader(HttpHeaders.ACCEPT, "application/vnd.github+json")
.defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token)
.build();
}
public List<GithubRepo> reposOf(String org) {
return client.get()
.uri(uri -> uri.path("/orgs/{org}/repos")
.queryParam("sort", "updated")
.queryParam("per_page", 5)
.build(org))
.retrieve()
.body(new ParameterizedTypeReference<>() {});
}
}
githubClient.reposOf("spring-projects")
[GithubRepo[name=spring-boot, stars=77000, language=Java],
GithubRepo[name=spring-framework, stars=58000, language=Java], ...]
POST, PUT, DELETE and reading status and headers
public record CreatePaymentRequest(long amountPaise, String currency, String orderRef) {}
public record Payment(String id, String status) {}
public Payment createPayment(CreatePaymentRequest req, String idempotencyKey) {
ResponseEntity<Payment> response = client.post()
.uri("/v1/payments")
.contentType(MediaType.APPLICATION_JSON)
.header("Idempotency-Key", idempotencyKey)
.body(req)
.retrieve()
.toEntity(Payment.class);
log.info("status={} location={}", response.getStatusCode(), response.getHeaders().getLocation());
return response.getBody();
}
public void updateMetadata(String paymentId, Map<String, String> metadata) {
client.put().uri("/v1/payments/{id}/metadata", paymentId)
.body(metadata)
.retrieve()
.toBodilessEntity();
}
public void cancel(String paymentId) {
client.delete().uri("/v1/payments/{id}", paymentId).retrieve().toBodilessEntity();
}
status=201 CREATED location=https://pay.example.com/v1/payments/pay_91x
Payment[id=pay_91x, status=CREATED]
Translating error statuses into domain results
public Optional<Product> findProduct(long id) {
try {
return Optional.ofNullable(client.get()
.uri("/products/{id}", id)
.retrieve()
.onStatus(status -> status.value() == 404, (request, response) -> {
throw new ProductNotFoundException(id);
})
.onStatus(HttpStatusCode::is5xxServerError, (request, response) -> {
throw new CatalogUnavailableException("Catalog returned " + response.getStatusCode());
})
.body(Product.class));
} catch (ProductNotFoundException e) {
return Optional.empty();
} catch (ResourceAccessException e) { // connection refused, timeout
throw new CatalogUnavailableException("Catalog unreachable", e);
}
}
findProduct(1) -> Optional[Product[id=1, name=Hoodie]]
findProduct(999) -> Optional.empty
(catalog down) -> CatalogUnavailableException: Catalog unreachable
A logging interceptor applied to all RestClients
@Bean
RestClientCustomizer loggingCustomizer() {
return builder -> builder.requestInterceptor((request, body, execution) -> {
long start = System.nanoTime();
ClientHttpResponse response = execution.execute(request, body);
log.info("HTTP {} {} -> {} in {} ms", request.getMethod(), request.getURI(),
response.getStatusCode().value(), (System.nanoTime() - start) / 1_000_000);
return response;
});
}
INFO HTTP GET https://api.github.com/orgs/spring-projects/repos?sort=updated&per_page=5 -> 200 in 312 ms
Testing a client with MockRestServiceServer
// test dependency: spring-boot-starter-restclient-test
@RestClientTest(GithubClient.class)
@TestPropertySource(properties = {"github.base-url=https://api.github.com", "github.token=test"})
class GithubClientTest {
@Autowired GithubClient client;
@Autowired MockRestServiceServer server;
@Test
void parsesRepositories() {
server.expect(requestTo("https://api.github.com/orgs/webnest/repos?sort=updated&per_page=5"))
.andExpect(header("Authorization", "Bearer test"))
.andRespond(withSuccess("""
[{"name":"shop","stargazers_count":12,"language":"Java"}]
""", MediaType.APPLICATION_JSON));
assertThat(client.reposOf("webnest"))
.containsExactly(new GithubRepo("shop", 12, "Java"));
}
}
GithubClientTest > parsesRepositories() PASSED (no real network call)
Common Mistakes
- Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient.
- Creating RestClient.create() everywhere instead of using the auto-configured builder, losing shared JSON settings and customizers.
- Not setting connect and read timeouts, so a slow partner API exhausts your request threads.
- Building URLs by string concatenation with user input instead of URI templates, breaking encoding and enabling injection.
- Catching every exception and returning null, hiding outages from monitoring.
- Calling URLs supplied by users without SSRF protection.
Exercise
Using the lesson's A client for an external API built from the auto-configured builder example, create a small implementation or design sketch that demonstrates RestClient is the modern synchronous HTTP client for Spring MVC applications.. Add a test case or scenario that would catch Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient., and describe the expected result.
Show hints
- Start with RestClient vs RestTemplate vs WebClient and compare your approach with A client for an external API built from the auto-configured builder. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows RestClient is the modern synchronous HTTP client for Spring MVC applications. and that it would catch the failure described by Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient..
Quick quiz
1. Which choice is a mistake to avoid in Calling REST APIs with RestClient?
- A. Creating RestClient.create() everywhere instead of using the auto-configured builder, losing shared JSON settings and customizers.
- B. RestClient is the modern synchronous HTTP client for Spring MVC applications.
- C. Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient.
Show answer
C. Avoid this approach: Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient. The lesson recommends: RestClient is the modern synchronous HTTP client for Spring MVC applications.
Interview questions
A teammate is about to make this mistake: Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient. How would you diagnose and correct it using the lesson's guidance?
Show answer
RestClient is the modern synchronous HTTP client for Spring MVC applications. Apply this in RestClient vs RestTemplate vs WebClient; the example A client for an external API built from the auto-configured builder shows one way to do it. Avoid Expecting RestClient.Builder to be injectable in Spring Boot 4 with only spring-boot-starter-webmvc; add spring-boot-starter-restclient. and explain how your implementation or design prevents that failure.
Key Points to Remember
- RestClient is the modern synchronous HTTP client for Spring MVC applications.
- Inject the auto-configured RestClient.Builder and configure one client per remote service.
- retrieve().body(), toEntity() and toBodilessEntity() cover most response needs.
- Use onStatus to map HTTP errors to domain exceptions; set timeouts via spring.http.clients.*.
- Test clients with @RestClientTest and MockRestServiceServer.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering