DEV Community: pallavi kamble

🚀 Mastering Asynchronous API Calls with Spring WebClient

pallavi kamble — Sat, 11 Oct 2025 12:34:47 +0000

In modern microservices, non-blocking asynchronous communication is critical to building scalable and resilient systems. Spring WebClient, part of Spring WebFlux, makes it easy to perform asynchronous HTTP calls, replacing the older, blocking RestTemplate.

This blog covers how to use WebClient for asynchronous communication, including examples, chaining, parallel calls, and error handling.

What is WebClient?

WebClient is a reactive, non-blocking HTTP client. Unlike RestTemplate, it doesn’t block the thread while waiting for a response. Instead, it returns reactive types:

Mono – Represents 0 or 1 element.

Flux – Represents 0 or N elements.

This enables high throughput and efficient use of resources, especially when calling multiple microservices concurrently.

Commonly Used Methods in Mono and Flux

1. flatMap → Chain Service Calls
flatMap is used to call another asynchronous method and flatten the result into the same pipeline. This is the most important method when chaining multiple WebClient calls.

2. map → Transform Response
map is used to transform the value inside a Mono or Flux synchronously.

3. zip → Combine Multiple Responses
zip is used when responses from multiple services need to be combined.

4. onErrorResume → Handle Failures Gracefully
onErrorResume helps in applying fallback logic when a failure occurs. Often used for resilience patterns, like returning fallback responses or calling a backup service.

5. doOnNext → Logging and Debugging
doOnNext executes side-effects whenever a new element is emitted, without modifying the actual data.

Benefits of Using Mono & Flux
1. Non-blocking: Your app can handle many requests without blocking threads.
2. Backpressure support: Consumers can control the rate at which data is emitted.
3. Composability: Easy to chain operations like map(), filter(), flatMap().
4. Error handling: Clean handling of errors without try/catch blocks.
5. Streaming: Ideal for reactive APIs, WebSockets, or real-time data.

Blocking vs. Non-blocking API Calls

Blocking API Calls:
The caller waits for the response before moving on.
The thread that makes the call is blocked until the operation completes.
Easy to understand and implement but not scalable for high-load systems.

    @GetMapping("/blocking/product/{id}")
    public ProductResponse getProductBlocking(@PathVariable Long id) {
        return WebClient.create("http://localhost:8081/products")
                .get()
                .uri("/{id}", id)
                .retrieve()
                .bodyToMono(ProductResponse.class)
                .block();
    }

Non-blocking API Calls:
The caller does not wait, it continues execution immediately.
The response is handled asynchronously when it arrives.
More scalable, efficient, and ideal for reactive programming.

@GetMapping("/nonblocking/product/{id}")
public Mono<ProductResponse> getProductNonBlocking(@PathVariable Long id) {
    return WebClient.create("http://localhost:8081/products")
            .get()
            .uri("/{id}", id)
            .retrieve()
            .bodyToMono(ProductResponse.class);
}

HTTP Methods in WebClient

1. GET Method:
GET API to fetches either a collection of resources or a singular resource.
Example 1: Use Mono to fetch only a single resource.

public Mono<ProductResponse> getProductById(Long productId) {
        return productClient.get()
                .uri("/{id}", productId)
                .retrieve()
                .bodyToMono(ProductResponse.class);
    }

Example 2: Use Flux to fetch a collection of resources.

 public Flux<ProductResponse> getAllProducts() {
        return productClient.get()
                .uri("/")
                .retrieve()
                .bodyToFlux(ProductResponse.class);
    }

2. POST Method:
Use to send data to the server to create a new resource.

public Mono<ProductResponse> createProduct(ProductRequest productRequest) {
        return productClient.post()
                .uri("/create")
                .bodyValue(productRequest)
                .retrieve()
                .bodyToMono(ProductResponse.class);
    }

3. PUT Method:
Use to replace an existing resource.

  public Mono<ProductResponse> updateProduct(Long productId, ProductRequest productRequest) {
        return productClient.put()
                .uri("/update/{id}", productId)
                .bodyValue(productRequest)
                .retrieve()
                .bodyToMono(ProductResponse.class);
    }

4. DELETE Method:
Use to delete a resource.

public Mono<Void> deleteProduct(Long productId) {
        return productClient.delete()
                .uri("/delete/{id}", productId)
                .retrieve()
                .bodyToMono(Void.class);
    }

5. Patch Method:
Use to update only part of a resource.

 public Mono<ProductResponse> reduceStock(Long productId, int quantity) {
        return productClient.patch()
                .uri(uriBuilder -> uriBuilder
                        .path("/{id}/reduceStock")
                        .queryParam("stock", quantity)
                        .build(productId))
                .retrieve()
                .bodyToMono(ProductResponse.class);
    }

Chaining, Composition, and Parallel Calls
One of the most powerful aspects of reactive programming in Spring WebFlux is the ability to chain operations, compose streams, and execute API calls in parallel.

1. Chaining: Sequential, dependent operations.
Chaining allows to apply multiple operations sequentially on a reactive stream Transformations, filters, or side effects can be performed without blocking the thread.

public Mono<String> chainingProductAndCustomer(Long productId, Long customerId) {
    return getCustomerById(customerId)
            .flatMap(customer ->
                    getProductById(productId)
                            .map(product -> 
                                "Customer: " + customer.getCustomerName() +
                                ", Product: " + product.getProductName()
                            )
            );
}

Explanation:
• getCustomerById() fetches a customer.
• Only after customer is fetched, getProductById() is called.
• Result combines customer and product info.

2. Composition: Dependent operations composed together.
Composition is about combining multiple reactive streams into one. This is particularly useful when making multiple API calls that either depend on each other or need to be merged.

public Mono<String> compositionExample(Long orderId) {
    return getOrderById(orderId)
            .flatMap(order -> getProductById(order.getProductId())
                    .flatMap(product -> getCustomerById(order.getCustomerId())
                            .map(customer -> 
                                "Order: " + order.getOrderId() +
                                ", Customer: " + customer.getCustomerName() +
                                ", Product: " + product.getProductName()
                            )
                    )
            );
}

Explanation:
• You fetch order, then based on order details, fetch product and customer.
• Uses nested flatMap, combining multiple dependent calls.

3. Flux Parallel Calls: Faster than chaining when calls don’t depend on each other.
When working with collections of IDs or items, Flux provides a convenient way to perform multiple parallel requests and merge their results.

public Mono<String> parallelExample(Long customerId, Long productId) {
    Mono<String> customerMono = getCustomerById(customerId).map(c -> "Customer: " + c.getCustomerName());
    Mono<String> productMono = getProductById(productId).map(p -> "Product: " + p.getProductName());

    return Mono.zip(customerMono, productMono)
            .map(tuple -> tuple.getT1() + " | " + tuple.getT2());
}

Explanation:
• getCustomerById() and getProductById() are independent → run in parallel.
• Mono.zip() combines results when both complete.

Exception Handling
In asynchronous communication with WebClient, exceptions are not managed using traditional try-catch blocks. Instead, they flow through the reactive pipeline (Mono or Flux). Operators such as onStatus, onErrorResume, onErrorReturn, and doOnError are used to handle them in a non-blocking manner.

1. Handling HTTP Error Status with onStatus()
When using retrieve(), WebClient automatically maps 2xx responses to the response body. Error statuses such as 4xx and 5xx require explicit handling through onStatus.
onStatus checks for error codes. Instead of returning a normal response, it maps them to a custom exception.

2. Fallback Mechanisms
Instead of failing the entire pipeline, a fallback strategy can be applied.
The operator onErrorReturn provides a static default response, while onErrorResume allows dynamic recovery, such as calling another service or applying conditional logic.

3. Timeout and Retry
Resilience in distributed systems often requires timeouts and retries. WebClient supports this directly in the reactive pipeline.

4. Centralized Error Handling
For consistent behavior across the application, exceptions can be handled globally using @ControllerAdvice.

Example of Asynchronous Communication
To demonstrate how reactive and asynchronous communication works in microservices, let’s build a simple e-commerce system using WebClient in Spring Boot.
The application consists of three services — Product Service, Customer Service, and Order Service — communicating asynchronously using Spring WebFlux and WebClient.

Product Service – Manages product details and stock.
Handles CRUD operations for products.
Exposes endpoints for GET, POST, PUT, PATCH, and DELETE.
The PATCH endpoint updates stock after order placement.

Customer Service – Manages customer information.
Handles customer data CRUD operations.
Independent service used by Order Service to validate customers.

Order Service – Places orders and communicates with both Product and Customer services.
The core service demonstrating async communication.
Uses WebClient to call Product and Customer services.
Includes examples of chaining, composition, and parallel calls.

In Order Service :

Defining as a Spring Bean for reuse.

@Configuration
public class WebClientConfig {

        @Bean
    public WebClient productWebClient() {
        HttpClient httpClient = HttpClient.create().option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
                .responseTimeout(Duration.ofSeconds(5))
                .doOnConnected(conn -> conn.addHandlerLast(new ReadTimeoutHandler(5, TimeUnit.SECONDS))
                        .addHandlerLast(new WriteTimeoutHandler(5, TimeUnit.SECONDS)));

        return WebClient.builder().baseUrl("http://localhost:8081/products")
                .clientConnector(new ReactorClientHttpConnector(httpClient)).build();
    }

    @Bean
    public WebClient customerWebClient() {
        HttpClient httpClient = HttpClient.create().option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000) 
                .responseTimeout(Duration.ofSeconds(5))
                .doOnConnected(conn -> conn.addHandlerLast(new ReadTimeoutHandler(5, TimeUnit.SECONDS))
                        .addHandlerLast(new WriteTimeoutHandler(5, TimeUnit.SECONDS)));

        return WebClient.builder().baseUrl("http://localhost:8082/customer")
                .clientConnector(new ReactorClientHttpConnector(httpClient)).build();
    }

}

Creating DTO Classes.

ProductResponse

@Data
public class ProductResponse {

    private Long productId;
    private String productName;
    private String productCategory;
    private Double productPrice;
    private Integer stock;

}

CustomerResponse

@Data
public class CustomerResponse {

    private Long customerId;
    private String customerName;
    private String email;
    private String address;
}

Creating Service.

@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final WebClient customerClient;
    private final WebClient productClient;

    @Autowired
    public OrderService(OrderRepository orderRepository, WebClient customerWebClient, WebClient productWebClient) {
        this.orderRepository = orderRepository;
        this.customerClient = customerWebClient;
        this.productClient = productWebClient;
    }

    // Get Customer by ID
    public Mono<CustomerResponse> getCustomerById(Long customerId) {
        return customerClient.get()
                .uri("/{id}", customerId)
                .retrieve()
                .onStatus(status -> status.is4xxClientError(), clientResponse -> 
                    clientResponse.bodyToMono(String.class)
                                  .flatMap(body -> Mono.error(new RuntimeException("Customer not found")))
                )
                .onStatus(status -> status.is5xxServerError(), clientResponse -> 
                    clientResponse.bodyToMono(String.class)
                                  .flatMap(body -> Mono.error(new RuntimeException("Customer service error")))
                )
                .bodyToMono(CustomerResponse.class)
                .timeout(Duration.ofSeconds(5))
                .doOnNext(c -> System.out.println("Fetched customer: " + c))
                .doOnError(e -> System.out.println("Error fetching customer: " + e.getMessage()));

    }

    // Get Product by ID
    public Mono<ProductResponse> getProductById(Long productId) {
        return productClient.get()
                .uri("/{id}", productId)
                .retrieve()
                .onStatus(status -> status.is4xxClientError(), clientResponse -> 
                    clientResponse.bodyToMono(String.class)
                                  .flatMap(body -> Mono.error(new RuntimeException("Product not found")))
                )
                .onStatus(status -> status.is5xxServerError(), clientResponse -> 
                    clientResponse.bodyToMono(String.class)
                                  .flatMap(body -> Mono.error(new RuntimeException("Product service error")))
                )
                .bodyToMono(ProductResponse.class)
                .timeout(Duration.ofSeconds(5))
                .onErrorResume(e -> {
                    System.out.println("Fallback triggered for product: " + e.getMessage());
                    ProductResponse fallback = new ProductResponse();
                    fallback.setProductId(productId);
                    fallback.setProductName("Fallback Product");
                    fallback.setStock(0);
                    fallback.setProductPrice(0.0);
                    return Mono.just(fallback); 
                });         
    }

    // Reduce stock
    public Mono<ProductResponse> reduceStock(Long productId, int stock) {
        return productClient.patch()
                .uri(uriBuilder -> uriBuilder
                        .path("/{id}/reduceStock")
                        .queryParam("stock", stock)
                        .build(productId))
                .retrieve()
                .onStatus(status -> status.is4xxClientError(), clientResponse -> 
                    clientResponse.bodyToMono(String.class)
                                  .flatMap(body -> Mono.error(new RuntimeException("Client error: " + body)))
                )
                .onStatus(status -> status.is5xxServerError(), clientResponse -> 
                    clientResponse.bodyToMono(String.class)
                                  .flatMap(body -> Mono.error(new RuntimeException("Server error: " + body)))
                )
                .bodyToMono(ProductResponse.class)
                .timeout(Duration.ofSeconds(5))
                .doOnNext(p -> System.out.println("Stock reduced: " + p))
                .doOnError(e -> System.out.println("Error calling reduceStock: " + e.getMessage()));
    }


    // Place Order
    public Mono<Order> placeOrder(Order order) {
        return getCustomerById(order.getCustomerId())
                .flatMap(customer -> 
                    getProductById(order.getProductId())
                        .flatMap(product -> {
                            if(product.getStock() < order.getQuantity()) {
                                return Mono.error(new RuntimeException("Insuffient Stock...!!!"));
                            }
                            return reduceStock(order.getProductId(), order.getQuantity())
                                    .flatMap(updatedProduct -> {
                                        order.setTotalPrice(order.getQuantity() * product.getProductPrice());
                                        order.setCreatedAt(LocalDateTime.now());
                                        return orderRepository.save(order)  ;   
                                    });
                        }) 
                )
        .doOnError(e -> System.out.println("Error in placing order: " + e.getMessage()));
    }

}

Create Controller.

@RestController
@RequestMapping("/order")
public class OrderController {

    private final OrderService orderService;

    @Autowired
    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    @PostMapping("/create")
    public Mono<Order> placeOrder(@RequestBody Order order) {
        // Return the reactive stream directly
        return orderService.placeOrder(order);
    }
}

Curl:

curl --location 'http://localhost:8083/order/create' \
--header 'Content-Type: application/json' \
--data '{
  "customerId": 2,
  "productId": 2,
  "quantity": 1
}'

Conclusion
WebClient in Spring Boot offers a powerful and reactive way to handle inter-service communication. Through this blog, we explored configuration, asynchronous calls, chaining, composition, and error handling with Mono and Flux. The example project demonstrated how multiple services can interact efficiently in a non-blocking manner, making WebClient an ideal choice for modern microservice communication.

🚀 Mastering Synchronous API Calls with Spring WebClient

pallavi kamble — Mon, 06 Oct 2025 16:26:10 +0000

In modern microservices architecture, services frequently need to communicate with each other or with external APIs over HTTP. Traditionally, developers relied on RestTemplate for such calls, but with the rise of reactive programming and the need for better scalability, Spring introduced WebClient as part of the Spring WebFlux module.

WebClient is a non-blocking, reactive HTTP client that supports both synchronous and asynchronous communication. It is lightweight, efficient, and designed to handle high-concurrency scenarios, making it the preferred choice for building resilient and scalable microservices.

🔹 Features of WebClient in Spring Boot

Non-blocking & Reactive – Built on Project Reactor, it supports asynchronous and non-blocking communication, improving scalability.

Supports All HTTP Methods – Works with GET, POST, PUT, DELETE, PATCH, and more.

Flexible Response Handling – Convert responses into Mono (single object) or Flux (multiple objects/streams).

Customizable Requests – Easy to add headers, query parameters, cookies, and authentication tokens.

Error Handling – Provides built-in error handling for 4xx/5xx and customizable handling with .onStatus().

Lightweight & Future-Proof – Official replacement for RestTemplate, designed for cloud-native applications.

🔹Reactive Types – Mono and Flux

When using WebClient, the HTTP response is not returned immediately like a traditional call. Instead, it is wrapped in a reactive type which represents a pipeline of data that will be available in the future.

To actually read the response body, we use .retrieve(), which triggers the HTTP call and prepares the response for conversion into Mono or Flux.

Spring WebFlux uses Project Reactor, which provides two main reactive types:

Mono – Single or No Result
Represents 0 or 1 item.
Use when the API returns a single object or might be empty.
Examples: fetching a single customer, saving an entity, deleting by ID.

Flux – Multiple or Stream of Results
Represents 0 to N items.
Use when the API returns a list of items or a continuous stream.
Examples: fetching all customers, streaming logs, Server-Sent Events.

🔹 WebClient Configuration

Add Dependency

<dependency>
    <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

Defining as a Spring Bean for reuse.

@Configuration
public class WebClientConfig {
    @Bean
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder();
    }
}

Inject Webclient

@Service
public class BookingService {

    private final WebClient webClient;

    @Autowired
    public BookingService(WebClient.Builder webClientBuilder) {
         this.webClient = webClientBuilder.baseUrl("http://localhost:8081").build(); 
    }
}

🔹 GET API Example
GET API is use to fetch either a collection of resources or a singular resource

• HTTP GET /hotel: List of Hotel as Flux

     public List<HotelResponse> getAllHotels() {
         return webClient
                    .get()  
                    .uri("/hotel")
                    .retrieve()
                    .bodyToFlux(HotelResponse.class)
                    .collectList()
                    .block();
      }

• HTTP GET /hotel/{id}: single hotel by id as Mono

HotelResponse hotel = webClient
                .get()
                .uri("hotel/{id}", booking.getHotelId())
                .retrieve()
                .bodyToMono(HotelResponse.class)
                .block();

🔹 PUT API Example
PUT API is commonly used for updating a resource.

webClient.put()
                    .uri("/hotel/{id}/update-rooms?bookedRooms={count}",
                            booking.getHotelId(), booking.getNoOfRoomsBooked())
                    .retrieve()
                    .bodyToMono(Void.class)
                    .block();

🔹 Exception Handling in WebClient

When working with microservices, one service often calls another over HTTP. But what happens if the target service is down, or returns an error (like 404 or 500)? Without proper handling, users might see raw stack traces or cryptic messages.

With Spring WebClient, we can gracefully handle these errors using .onStatus() and @ControllerAdvice.

Error Handling in WebClient
.onStatus() : handle remote service failures.

    HotelResponse hotel = webClient
                .get()
                .uri("hotel/{id}", booking.getHotelId())
                .retrieve()
                .onStatus(
                          status -> status.is4xxClientError(),
                          response -> response.bodyToMono(String.class)
                                            .map(msg -> new RuntimeException("Hotel not found: " + msg))
                        )
                .onStatus(
                          status -> status.is5xxServerError(),
                          response -> response.bodyToMono(String.class)
                                               .map(msg -> new RuntimeException("Hotel Service error: " + msg))
                        )
                .bodyToMono(HotelResponse.class)
                .block();

Global Exception Handling with @ControllerAdvice
At the application level, we can use @RestControllerAdvice to catch exceptions globally and return clean JSON responses instead of stack traces.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<Map<String, Object>> handleRuntimeException(RuntimeException ex) {
        Map<String, Object> error = new HashMap<>();
        error.put("error", ex.getMessage());
        error.put("timestamp", LocalDateTime.now());
        error.put("status", HttpStatus.BAD_REQUEST.value());
        return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handleException(Exception ex) {
        Map<String, Object> error = new HashMap<>();
        error.put("error", "Internal server error");
        error.put("details", ex.getMessage());
        error.put("timestamp", LocalDateTime.now());
        error.put("status", HttpStatus.INTERNAL_SERVER_ERROR.value());
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }

}

🔹 Connection Timeouts

Connection timeouts are critical in Spring WebClient to prevent your application from waiting indefinitely when calling slow or unresponsive services. Configuring timeouts ensures microservices remain responsive, resilient, and production-ready.

Types of Timeouts in WebClient
With WebClient (backed by Reactor Netty), there are three main timeout types:
Connection Timeout: Maximum time allowed to establish a TCP connection.
Response Timeout: Maximum time to wait for the first byte of the response.
Read/Write Timeout: Maximum time allowed for reading or writing data once connected.

Example: Configure Timeouts in WebClient
Configure timeouts when building a WebClient using Reactor Netty:

@Configuration
public class WebClientConfig {
    @Bean
    public WebClient.Builder webClientBuilder() {

        HttpClient httpClient = HttpClient.create()
                // 1. Connection Timeout
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000)
                // 2. Response Timeout
                .responseTimeout(Duration.ofSeconds(5))
                // 3. Read & Write Timeout
                .doOnConnected(conn -> 
                        conn.addHandlerLast(new ReadTimeoutHandler(5, TimeUnit.SECONDS))
                            .addHandlerLast(new WriteTimeoutHandler(5, TimeUnit.SECONDS))
                );

        return WebClient.builder()
                .clientConnector(new ReactorClientHttpConnector(httpClient));
    }
}

Using Request-Level Timeout
Add a per-request timeout as an extra safety net:

HotelResponse hotel = webClient
                .get()
                .uri("hotel/{id}", booking.getHotelId())
                .retrieve()
                .bodyToMono(HotelResponse.class)
                .timeout(Duration.ofSeconds(3))
                .block();

🔹Conclusion

In microservices, WebClient gives developers a modern and reactive way to handle HTTP communication. Even when used synchronously with .block(), it provides better flexibility and cleaner APIs compared to the legacy RestTemplate. As Spring continues to evolve, WebClient stands out as the go-to option for building robust service-to-service communication.

Mastering RestTemplate in Spring Boot

pallavi kamble — Sat, 27 Sep 2025 12:40:50 +0000

When building microservices or REST-based applications, it’s common to make HTTP calls from one service to another. In Spring Boot, the traditional and widely used approach for this (before WebClient) is RestTemplate. It provides a simple, synchronous way to perform GET, POST, PUT, DELETE, and other HTTP requests. In this post, we’ll explore practical examples of using RestTemplate, including sending custom headers, handling responses, and performing CRUD operations between services like a Customer Service and an Account Service.

What is RestTemplate?

RestTemplate is a synchronous client provided by the Spring Framework to make HTTP requests to RESTful web services.
It handles HTTP communication and internally relies on java.net.HttpURLConnection, simplifying interaction with external services.
It offers convenience, flexibility, and seamless integration for various HTTP operations. Think of it as a Java client that enables your Spring Boot application to consume REST APIs easily.

Key Features of RestTemplate

1. Synchronous HTTP Calls
RestTemplate executes HTTP requests synchronously, meaning the thread waits for the response before continuing. It’s simple and widely used for service-to-service communication.

2. Multiple HTTP Methods
Supports GET, POST, PUT, PATCH, DELETE, and OPTIONS, making it easy to perform full CRUD operations.

3. Flexible Response Handling
Fetch just the response body (getForObject()), access the full response with status and headers (getForEntity()), or use exchange() for complete control over requests and responses.

4. URI Template Support
Use placeholders ({id}) in URLs to dynamically insert values.

5. Request Body Handling
Send Java objects as JSON or XML and automatically map responses to Java objects.

6. Custom Headers
Add headers using HttpEntity and HttpHeaders for authentication, tracing, or extra metadata.

7. Exception Handling
RestTemplate throws exceptions for HTTP errors (4xx, 5xx) which can be caught or customized with ResponseErrorHandler.

8. Interceptors and Request Factories
Use ClientHttpRequestInterceptor for logging or authentication. Swap the underlying HTTP client via ClientHttpRequestFactory for timeouts, pooling, or advanced configuration.

Setting Up RestTemplate in Spring Boot

Add Dependency
If you’re using Spring Boot Starter Web, RestTemplate is already included. Otherwise, add this to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Define RestTemplate as a Bean

@Configuration
public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }

}

Inject RestTemplate

@Service
public class AccountService {

    private RestTemplate restTemplate;

    public AccountService(RestTemplate restTemplate) {  
        this.restTemplate = restTemplate;
    }
}

Common Methods of RestTemplate

1. GET Operations :

- getForObject() : Fetches a resource as an object.

Service:

    public CustomerDto getAccountWithCustomer(Long customerId) {

        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers";
        return restTemplate.getForObject(CUSTOMER_SERVICE_URL + "/{id}", 
                                            CustomerDto.class, 
                                            customerId);

    }

Controller:

@GetMapping("/{id}")
    public CustomerDto getAccountWithCustomer(@PathVariable Long id) {
        return accountService.getAccountWithCustomer(id);   
    }

cURL:

curl --location 'http://localhost:8082/accounts/5' \
--data ''

- getForEntity() : Fetches a resource with HTTP status and headers.

Service:

public CustomerDto getCustomerWithGetForEntity(Long customerId) {
        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers";
        ResponseEntity<CustomerDto> response = 
                restTemplate.getForEntity(
                                CUSTOMER_SERVICE_URL + "/{id}", 
                                CustomerDto.class, 
                                customerId
                );
        System.out.println("Status Code: " + response.getStatusCode());
        System.out.println("Headers: " + response.getHeaders());
        return response.getBody();
    }

Controller:

@GetMapping("/cust/{id}")
    public CustomerDto getCustomerWithGetForEntity(@PathVariable Long id) {
        return accountService.getCustomerWithGetForEntity(id);  
    }

cURL:

curl --location 'http://localhost:8082/accounts/cust/5'

- exchange(): Flexible method for any HTTP method with headers, body, and status.

Service:

    public CustomerDto getCustomerWithExchange(Long customerId) {
        HttpHeaders headers = new HttpHeaders();
        headers.set("Custom-Header", "customer");
        HttpEntity<Void> entity = new HttpEntity<>(headers);

        ResponseEntity<CustomerDto> response = restTemplate.exchange(
                CUSTOMER_SERVICE_URL + "/{id}",
                HttpMethod.GET,
                entity,
                CustomerDto.class,
                customerId
        );

        System.out.println("Status Code: " + response.getStatusCode());
        System.out.println("Headers: " + response.getHeaders());
        return response.getBody();
    }

Controller:

@GetMapping("/exchange/{id}")
    public CustomerDto getCustomerWithExchange(@PathVariable Long id) {
        return accountService.getCustomerWithExchange(id);
    }

cURL:

curl --location 'http://localhost:8082/accounts/exchange/2' \
--header 'Custom-Header: customer' \
--data ''

2. POST Operations:

- postForObject() : Sends a POST request and retrieves the response body.

Service:

public CustomerDto createCustomerWithPostForObject(CustomerDto customer) {
        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers/create";
        return restTemplate.postForObject(CUSTOMER_SERVICE_URL, 
                                            customer, 
                                            CustomerDto.class);
    }

Controller:

@PostMapping("/cust")
    public CustomerDto createCustomerWithPostForObject(@RequestBody CustomerDto customer) {
        return accountService.createCustomerWithPostForObject(customer);
    }

cURL:

curl --location 'http://localhost:8082/accounts/cust' \
--header 'Content-Type: application/json' \
--data-raw '{
           "firstName": "Lara",
           "lastName": "Jean",
           "email": "lara@example.com",
           "mobileNo": "09873455672"
         }'

- postForEntity() : Sends a POST request and returns a ResponseEntity containing status, headers, and body.

Service:

public CustomerDto createCustomerWithPostForEntity(CustomerDto customer) {
        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers/create";
        ResponseEntity<CustomerDto> response = 
                restTemplate.postForEntity(
                CUSTOMER_SERVICE_URL, customer, CustomerDto.class
                );
        System.out.println("Status Code: " + response.getStatusCode());
        return response.getBody();
    }

Controller:

@PostMapping("/createCustomer")
    public CustomerDto createCustomerWithPostForEntity(@RequestBody CustomerDto customer) {
        return accountService.createCustomerWithPostForEntity(customer);
    }

cURL:

curl --location 'http://localhost:8082/accounts/customer' \
--header 'Content-Type: application/json' \
--data-raw '        {
           "firstName": "Martin",
           "lastName": "Wood",
           "email": "wood@example.com",
           "mobileNo": "9876655443"
         }'

3. PUT Operation:

- put() : Updates an existing resource.

Service:

 public String updateCustomer(CustomerDto updatedCustomer) {
        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers/update";
        restTemplate.put(CUSTOMER_SERVICE_URL, 
                        updatedCustomer);
        return "Customer Updated Successfully...!";
    }

Controller:

@PutMapping("/customer")
    public void updateCustomer(@RequestBody CustomerDto customer) {
        accountService.updateCustomer(customer);
    }

cURL:

curl --location --request PUT 'http://localhost:8082/accounts/customer' \
--header 'Content-Type: application/json' \
--data-raw '    {
    "customerId": "2",
  "firstName": "Sam",
  "lastName": "Smith",
  "email": "sam@gmail.com",
  "mobileNo": "9876556651"
}'

4. DELETE Operation:

- delete() : Deletes a resource.

Service:

 public String deleteCustomer(Long customerId) {
        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers/delete";
        restTemplate.delete(CUSTOMER_SERVICE_URL + "/{id}", 
                            customerId);
        return "Customer Deleted Successfully...!";
    }

Controller:

 @DeleteMapping("/customer/{id}")
    public String deleteCustomer(@PathVariable Long id) {
        return accountService.deleteCustomer(id);
    }

cURL:

curl --location --request DELETE 'http://localhost:8082/accounts/customer/11' \
--data ''

Exception Handling with RestTemplate

When calling external REST APIs using RestTemplate, things don’t always go as expected. Network issues, unavailable services, or server errors can occur, resulting in exceptions.
Proper exception handling ensures your application can gracefully handle errors, provide meaningful messages, and prevent crashes.
In Spring Boot, you can handle exceptions locally within service methods or globally using @ControllerAdvice and @ExceptionHandler.

Common Exceptions

HttpClientErrorException : 4xx HTTP errors (e.g., 404 Not Found, 400 Bad Request)
HttpServerErrorException : 5xx HTTP errors (e.g., 500 Internal Server Error)
ResourceAccessException : Network errors, timeouts, or unreachable host
RestClientException : Generic error if none of the above match

Handle Exceptions Locally
Wrap your RestTemplate calls in a try-catch block:
This approach is simple for service-level error handling.

 public CustomerDto getCustomerById(Long customerId) {
        String CUSTOMER_SERVICE_URL = "http://localhost:8081/customers/{id}";
        try {
            return restTemplate.getForObject(CUSTOMER_SERVICE_URL, CustomerDto.class, customerId);
        } catch (HttpClientErrorException.NotFound e) {
            throw new RuntimeException("Customer not found with ID: " + customerId);
        } catch (HttpClientErrorException e) {
            throw new RuntimeException("Client Error: " + e.getStatusCode());
        } catch (HttpServerErrorException e) {
            throw new RuntimeException("Server Error: " + e.getStatusCode());
        } catch (ResourceAccessException e) {
            throw new RuntimeException("Service unreachable: " + e.getMessage());
        }
    }

Global Exception Handling with @ControllerAdvice
You can also handle exceptions globally in your Spring Boot application.


@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(HttpClientErrorException.NotFound.class)
    public ResponseEntity<String> handleNotFound(HttpClientErrorException.NotFound ex) {
        return new ResponseEntity<>("Resource not found: " + ex.getMessage(), 
                                    HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(HttpClientErrorException.class)
    public ResponseEntity<String> handleClientError(HttpClientErrorException ex) {
        return new ResponseEntity<>("Client Error: " + ex.getStatusCode(), 
                                    HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(HttpServerErrorException.class)
    public ResponseEntity<String> handleServerError(HttpServerErrorException ex) {
        return new ResponseEntity<>("Server Error: " + ex.getStatusCode(), 
                                    HttpStatus.INTERNAL_SERVER_ERROR);
    }

    @ExceptionHandler(ResourceAccessException.class)
    public ResponseEntity<String> handleResourceAccess(ResourceAccessException ex) {
        return new ResponseEntity<>("Service unreachable: " + ex.getMessage(), 
                                    HttpStatus.SERVICE_UNAVAILABLE);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleGenericException(Exception ex) {
        return new ResponseEntity<>("Error: " + ex.getMessage(), 
                                    HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

How It Works :

When AccountService calls CustomerService via RestTemplate, it might throw exceptions like HttpClientErrorException or ResourceAccessException.
Spring automatically detects these exceptions in the same application context (AccountService) and routes them to your GlobalExceptionHandler.
You don’t need to write try-catch in every method, unless you want customized local handling.

Connection Pooling with RestTemplate

By default, RestTemplate creates a new HTTP connection for each request. This is fine for low-traffic apps, but under load, it can impact the performance. Using connection pooling allows to reuse connections and improve efficiency.

RestTemplate uses SimpleClientHttpRequestFactory, which:

Opens a new TCP connection for every HTTP request.
Closes the connection immediately after the request is done.

Problem:

Every new connection involves TCP handshake + SSL handshake (if HTTPS) → expensive.
For high-traffic microservices or APIs, this leads to performance bottlenecks.

Solution: Connection pooling.

Keep a pool of reusable HTTP connections open.
Requests reuse idle connections instead of creating new ones.
Reduces latency and improves throughput.

How RestTemplate Uses Connection Pooling

RestTemplate doesn’t support pooling directly. We need Apache HttpClient.

Apache HttpClient has PoolingHttpClientConnectionManager that manages reusable connections.
HttpComponentsClientHttpRequestFactory allows RestTemplate to use this HttpClient.

Add Apache HttpClient Dependency

<dependency>
            <groupId>org.apache.httpcomponents.client5</groupId>
            <artifactId>httpclient5</artifactId>
        </dependency>

Configure RestTemplate with Connection Pooling

@Configuration
public class RestTemplateConfig {

    @Bean
    public RestTemplate restTemplate() {

        // 1. Setup connection pool
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(50);      
        connectionManager.setDefaultMaxPerRoute(20);

        // 2. Build HttpClient with connection manager
        CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .build();

        // 3. Create RestTemplate factory
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory();
        factory.setHttpClient(httpClient);
        factory.setConnectTimeout(5000);
        factory.setReadTimeout(5000);

        return new RestTemplate(factory);

    }
}

MaxTotal: Maximum connections the pool can hold in total.
DefaultMaxPerRoute: Maximum connections to a single host.

Example: If your app talks to 3 services, the pool can hold up to 50 connections overall, but a single service will not exceed 20 concurrent connections.

CloseableHttpClient is a thread-safe HttpClient. It uses the PoolingHttpClientConnectionManager internally.
Connect Timeout: Max time to establish TCP connection.
Read Timeout: Max time to wait for the response after connection.

This ensures that your app doesn’t hang indefinitely if a service is slow or unresponsive.

Benefits of Using Connection Pooling

Reduced latency : Avoids repeated TCP/SSL handshakes.
Improved throughput : Handles more requests simultaneously.
Resource efficiency : Less CPU and network usage.
Stability under load : Prevents connection exhaustion during spikes.

Note on Deprecation

RestTemplate has been officially deprecated by the Spring team and is no longer being actively developed. The recommended alternative is WebClient, which offers non-blocking, reactive, and more scalable HTTP communication.

That said, RestTemplate is still heavily used in real-world projects and widely found in production codebases. Understanding it is essential if you’re maintaining existing applications or working in environments that haven’t fully migrated to WebClient.

Conclusion

We explored RestTemplate in depth — from its features and flexible methods to practical CRUD examples, handling custom headers, and managing exceptions. RestTemplate has long been the go-to tool for synchronous HTTP communication in Spring Boot, making it easy to connect services in a microservice architecture.

Takeaway: RestTemplate may be deprecated, but with proper setup — including exception handling and connection pooling — it remains a powerful tool in legacy systems, while WebClient leads the way for modern applications.