Setup and Examples for the Spring WebFlux WebClient

Last Updated: May 19, 2021 | Published: June 23, 2019

RESTful communication is the de-facto standard for interchanging data in a microservice-based environment. Usually, every participating microservice offers different parts of the application's domain in a RESTful way and calls other microservices to gather data for e.g. a different part of the application's domain. Resilience and efficient data interchange is, therefore, a key factor when it comes to the success of the whole application. With Spring we usually made use of the RestTemplate to perform HTTP requests, but can now also use the Spring WebClient.

With the release of Spring Framework 5.0, the documentation of the RestTemplate says the following:

NOTE: As of 5.0, the non-blocking, reactive org.springframework.web.reactive.client.WebClient offers a modern alternative to the RestTemplate with efficient support for both sync and async, as well as streaming scenarios. The RestTemplatewill be deprecated in a future version and will not have major new features added going forward. See the WebClient section of the Spring Framework reference documentation for more details and example code.

To be future-ready, your Spring-based application should migrate to the reactive and non-blocking Spring WebClient for both its async & sync HTTP communication.

With this blog post, you'll learn how to effectively use the WebClient class for HTTP requests. Furthermore, we'll take a look at the WebClient configuration, filtering requests, and testing. For the demo application, we'll use Java 11 and Spring Boot 2.4.

Create and Configure the WebClient

To take advantage of the WebClient, we need the following dependency for our Spring Boot project:

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

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-webflux</artifactId>

</dependency>

The WebClient internally delegates to an HTTP client library (by default Reactor Netty), but others can be plugged in through a ClientHttpConnector.

When it comes to configuring resilient HTTP clients, connection/read/write timeouts are important to avoid long-running tasks. In addition, HTTP headers and cookies are essential for e.g. authentication or content negotiation. We can configure such timeouts when creating our WebClient instance.

When using the WebClient within a Spring Boot project, we can inject the auto-configured WebClient.Builder and create the instance using this builder. This auto-configured builder customizes the WebClient to, among other things, emit metrics about the HTTP response code and response time when the Spring Boot Actuator is on the classpath:

@Bean
public WebClient webClientFromBuilder(WebClient.Builder webClientBuilder) {

  HttpClient httpClient = HttpClient.create()
    .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2_000) // millis
    .doOnConnected(connection ->
      connection
        .addHandlerLast(new ReadTimeoutHandler(2)) // seconds
        .addHandlerLast(new WriteTimeoutHandler(2))); //seconds

  return webClientBuilder
    .baseUrl(BASE_URL)
    .clientConnector(new ReactorClientHttpConnector(httpClient))
    .defaultCookie("cookieKey", "cookieValue", "teapot", "amsterdam")
    .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
    .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)
    .defaultHeader(HttpHeaders.USER_AGENT, "I'm a teapot")
    .filter(ExchangeFilterFunctions.basicAuthentication("rieckpil", UUID.randomUUID().toString()))
    .filter(logRequest())
    .filter(logResponse())
    .build();
}

@Bean

public WebClient webClientFromBuilder(WebClient.Builder webClientBuilder) {

HttpClient httpClient = HttpClient.create()

.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2_000) // millis

.doOnConnected(connection ->

connection

.addHandlerLast(new ReadTimeoutHandler(2)) // seconds

.addHandlerLast(new WriteTimeoutHandler(2))); //seconds

return webClientBuilder

.baseUrl(BASE_URL)

.clientConnector(new ReactorClientHttpConnector(httpClient))

.defaultCookie("cookieKey", "cookieValue", "teapot", "amsterdam")

.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)

.defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)

.defaultHeader(HttpHeaders.USER_AGENT, "I'm a teapot")

.filter(ExchangeFilterFunctions.basicAuthentication("rieckpil", UUID.randomUUID().toString()))

.filter(logRequest())

.filter(logResponse())

.build();

}

The configuration above defines convenient defaults for the connect, read and write timeouts. Furthermore, we define default cookies, headers, and filters that are presented (unless we override them) for each request made with this WebClient bean. More about the filtering mechanism in one of the upcoming sections.

We can also create our own WebClient from scratch without using the pre-configured WebClient.Builder from Spring Boot:

@Component
public class SimpleWebClientConfiguration {

  private static final String BASE_URL = "https://jsonplaceholder.typicode.com";
  private static final Logger logger = LoggerFactory.getLogger(SimpleApiClient.class);

  @Bean
  public WebClient webClientFromScratch() {

    return WebClient.builder()
      .baseUrl(BASE_URL)
      // similiar configuration
      .build();
  }
}

@Component

public class SimpleWebClientConfiguration {

private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

private static final Logger logger = LoggerFactory.getLogger(SimpleApiClient.class);

@Bean

public WebClient webClientFromScratch() {

return WebClient.builder()

.baseUrl(BASE_URL)

// similiar configuration

.build();

}

HTTP GET Request Example With Spring WebClient

Once our WebClient is configured for a specific baseUrl, we can start performing HTTP requests.

As the internal WebClient architecture is designed for reactive and non-blocking applications, we either have to call .block() or rewrite our codebase to accept Mono<T> and Flux<T> as method return types.

A simple sync HTTP GET request with our previously configured WebClient looks like the following:

@Service
public class SimpleApiClient {

  private final WebClient defaultWebClient;
  
  // inject the configured WebClient @Bean from the configuration above
  public SimpleApiClient(WebClient defaultWebClient) {
    this.defaultWebClient = defaultWebClient;
  }

  public JsonNode getTodoFromAPI() {
    return this.defaultWebClient
     .get()
     .uri("/todos/1")
     .retrieve()
     .bodyToMono(JsonNode.class)
     .block();
  }
}

@Service

public class SimpleApiClient {

private final WebClient defaultWebClient;

// inject the configured WebClient @Bean from the configuration above

public SimpleApiClient(WebClient defaultWebClient) {

this.defaultWebClient = defaultWebClient;

}

public JsonNode getTodoFromAPI() {

return this.defaultWebClient

.get()

.uri("/todos/1")

.retrieve()

.bodyToMono(JsonNode.class)

.block();

}

To trigger the actual HTTP request, we can either use .retrieve() or .exchange() whereby the first method is the preferred way. With .exchange(), we have more control about the response but also more responsibilities. Take a look at this blog post or the relevant part of the documentation to understand their difference in detail.

All upcoming examples use the preferred .retrieve() method.

Handle Different HTTP Response Codes

By default, HTTP responses with 4xx (e.g. 404 for not found) or 5xx (e.g. 500 service unavailable) status codes result in an WebClientResponseException.

For modifying the way how errors are handled, we can use the onStatus method of Spring's WebClient to customize the resulting exception:

@Service
public class SimpleApiClient {

  private final WebClient defaultWebClient;

  public SimpleApiClient(WebClient defaultWebClient) {
    this.defaultWebClient = defaultWebClient;
  }

  public JsonNode getTodoFromAPI() {
    return this.defaultWebClient
      .get()
      .uri("/todos/1")
      .retrieve()
      .onStatus(HttpStatus::is4xxClientError, response -> {
        System.out.println("4xx error");
        return Mono.error(new RuntimeException("4xx"));
      })
      .onStatus(HttpStatus::is5xxServerError, response -> {
        System.out.println("5xx error");
        return Mono.error(new RuntimeException("5xx"));
      })
      .bodyToMono(JsonNode.class)
      .block();
  }
}

@Service

public class SimpleApiClient {

private final WebClient defaultWebClient;

public SimpleApiClient(WebClient defaultWebClient) {

this.defaultWebClient = defaultWebClient;

}

public JsonNode getTodoFromAPI() {

return this.defaultWebClient

.get()

.uri("/todos/1")

.retrieve()

.onStatus(HttpStatus::is4xxClientError, response -> {

System.out.println("4xx error");

return Mono.error(new RuntimeException("4xx"));

})

.onStatus(HttpStatus::is5xxServerError, response -> {

System.out.println("5xx error");

return Mono.error(new RuntimeException("5xx"));

})

.bodyToMono(JsonNode.class)

.block();

}

HTTP GET Request Example With Spring WebClient

Performing HTTP POST request with the WebClient is as simple as the following:

@Service
public class SimpleApiClient {

  private final WebClient defaultWebClient;

  public SimpleApiClient(WebClient defaultWebClient) {
    this.defaultWebClient = defaultWebClient;
  }

  public JsonNode postToTodoAPI() {
    return this.defaultWebClient
      .post()
      .uri("/todos")
      .body(BodyInserters.fromValue("{ \"title\": \"foo\", \"body\": \"bar\", \"userId\": \"1\"}"))
      .retrieve()
      .bodyToMono(JsonNode.class)
      .block();
  }
}

@Service

public class SimpleApiClient {

private final WebClient defaultWebClient;

public SimpleApiClient(WebClient defaultWebClient) {

this.defaultWebClient = defaultWebClient;

}

public JsonNode postToTodoAPI() {

return this.defaultWebClient

.post()

.uri("/todos")

.body(BodyInserters.fromValue("{ \"title\": \"foo\", \"body\": \"bar\", \"userId\": \"1\"}"))

.retrieve()

.bodyToMono(JsonNode.class)

.block();

}

To put the request body in place, we can use the BodyInserters utility class and add any kind of Object, FormData, Publisher, MultipartData, Resource , etc.

Retry Configuration On Failure

For a more resilient architecture, we can configure retries for our WebClient . We can use the public methods of Mono and Flux for this purpose.

Let's say we want to retry two times (max. three HTTP calls) and add a small delay between each retry:

public JsonNode getRetryTodoFromAPI() {
  return this.defaultWebClient
    .get()
    .uri("/todos/1")
    .retrieve()
    .bodyToMono(JsonNode.class)
    .retryWhen(Retry.fixedDelay(2, Duration.ofMillis(300)))
    .block();
}

public JsonNode getRetryTodoFromAPI() {

return this.defaultWebClient

.get()

.uri("/todos/1")

.retrieve()

.bodyToMono(JsonNode.class)

.retryWhen(Retry.fixedDelay(2, Duration.ofMillis(300)))

.block();

}

Furthermore, we can combine the retry mechanism with a timeout from Mono or Flux to provide a fallback value:

public JsonNode getRetryTodoFromAPI() {
  return this.defaultWebClient
    .get()
    .uri("/todos/1")
    .retrieve()
    .bodyToMono(JsonNode.class)
    .retryWhen(Retry.max(5))
    .timeout(Duration.ofSeconds(2), 
         Mono.just(objectMapper.createObjectNode().put("message", "fallback")))
    .block();
}

public JsonNode getRetryTodoFromAPI() {

return this.defaultWebClient

.get()

.uri("/todos/1")

.retrieve()

.bodyToMono(JsonNode.class)

.retryWhen(Retry.max(5))

.timeout(Duration.ofSeconds(2),

Mono.just(objectMapper.createObjectNode().put("message", "fallback")))

.block();

}

Configure Filters for the Spring WebClient

If we have business logic or a configuration setup that applies to every HTTP request and response made with the WebClient, we can configure and chain multiple filters.

Logging the request/response might be such a requirement or adding authentication to the request. This is configured during the WebClient setup:

@Component
public class SimpleWebClientConfiguration {

  private static final String BASE_URL = "https://jsonplaceholder.typicode.com";
  private static final Logger logger = LoggerFactory.getLogger(SimpleApiClient.class);

  @Bean
  public WebClient webClientFromScratch() {

    // HttpClient configuration

    return WebClient.builder()
      .baseUrl(BASE_URL)
      .clientConnector(new ReactorClientHttpConnector(httpClient))
      .filter(ExchangeFilterFunctions.basicAuthentication("rieckpil", UUID.randomUUID().toString()))
      .filter(logRequest())
      .filter(logResponse())
      .build();
  }

  private ExchangeFilterFunction logRequest() {
    return (clientRequest, next) -> {
      logger.info("Request: {} {}", clientRequest.method(), clientRequest.url());
      logger.info("--- Http Headers: ---");
      clientRequest.headers().forEach(this::logHeader);
      logger.info("--- Http Cookies: ---");
      clientRequest.cookies().forEach(this::logHeader);
      return next.exchange(clientRequest);
    };
  }

  private ExchangeFilterFunction logResponse() {
    return ExchangeFilterFunction.ofResponseProcessor(clientResponse -> {
      logger.info("Response: {}", clientResponse.statusCode());
      clientResponse.headers().asHttpHeaders()
        .forEach((name, values) -> values.forEach(value -> logger.info("{}={}", name, value)));
      return Mono.just(clientResponse);
    });
  }

  private void logHeader(String name, List<String> values) {
    values.forEach(value -> logger.info("{}={}", name, value));
  }
}

@Component

public class SimpleWebClientConfiguration {

private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

private static final Logger logger = LoggerFactory.getLogger(SimpleApiClient.class);

@Bean

public WebClient webClientFromScratch() {

// HttpClient configuration

return WebClient.builder()

.baseUrl(BASE_URL)

.clientConnector(new ReactorClientHttpConnector(httpClient))

.filter(ExchangeFilterFunctions.basicAuthentication("rieckpil", UUID.randomUUID().toString()))

.filter(logRequest())

.filter(logResponse())

.build();

}

private ExchangeFilterFunction logRequest() {

return (clientRequest, next) -> {

logger.info("Request: {} {}", clientRequest.method(), clientRequest.url());

logger.info("--- Http Headers: ---");

clientRequest.headers().forEach(this::logHeader);

logger.info("--- Http Cookies: ---");

clientRequest.cookies().forEach(this::logHeader);

return next.exchange(clientRequest);

};

}

private ExchangeFilterFunction logResponse() {

return ExchangeFilterFunction.ofResponseProcessor(clientResponse -> {

logger.info("Response: {}", clientResponse.statusCode());

clientResponse.headers().asHttpHeaders()

.forEach((name, values) -> values.forEach(value -> logger.info("{}={}", name, value)));

return Mono.just(clientResponse);

});

}

private void logHeader(String name, List<String> values) {

values.forEach(value -> logger.info("{}={}", name, value));

}

We can also provide global customizations for our WebClient instances using the WebClientCustomizer interface.

Writing Tests For Classes Using the WebClient

When it comes to writing unit tests for API clients, mocking the entire WebClient interaction with Mockito is usually not a good fit. A better approach is to start a local HTTP server and mock the HTTP responses from the remote system:

class SimpleApiClientTest {

  private MockWebServer mockWebServer;
  private SimpleApiClient cut; // Class Under Test

  @BeforeEach
  void setup() throws IOException {
    this.mockWebServer = new MockWebServer();
    this.mockWebServer.start();
    this.cut = new SimpleApiClient(WebClient
      .builder()
      .baseUrl(mockWebServer.url("/").toString())
      .build());
  }

  @Test
  void testGetUserById() throws InterruptedException {
    MockResponse mockResponse = new MockResponse()
      .addHeader("Content-Type", "application/json; charset=utf-8")
      .setBody("{\"id\": 1, \"name\":\"write good tests\"}");

    mockWebServer.enqueue(mockResponse);

    JsonNode result = cut.getTodoFromAPI();

    assertEquals(1, result.get("id").asInt());
    assertEquals("write good tests", result.get("name").asText());

    RecordedRequest request = mockWebServer.takeRequest();
    assertEquals("/todos/1", request.getPath());
  }
}

class SimpleApiClientTest {

private MockWebServer mockWebServer;

private SimpleApiClient cut; // Class Under Test

@BeforeEach

void setup() throws IOException {

this.mockWebServer = new MockWebServer();

this.mockWebServer.start();

this.cut = new SimpleApiClient(WebClient

.builder()

.baseUrl(mockWebServer.url("/").toString())

.build());

}

@Test

void testGetUserById() throws InterruptedException {

MockResponse mockResponse = new MockResponse()

.addHeader("Content-Type", "application/json; charset=utf-8")

.setBody("{\"id\": 1, \"name\":\"write good tests\"}");

mockWebServer.enqueue(mockResponse);

JsonNode result = cut.getTodoFromAPI();

assertEquals(1, result.get("id").asInt());

assertEquals("write good tests", result.get("name").asText());

RecordedRequest request = mockWebServer.takeRequest();

assertEquals("/todos/1", request.getPath());

}

More information and examples for this test setup can be found here.

Integration Testing With the WebTestClient

For efficient integrations tests that test HTTP endpoints of our own application, we can use the WebTestClient. It's similar to the TestRestTemplate.

This client offers the same functionality as the normal WebClient but has additional methods for convention assertions and expectations for the HTTP result. As soon as we use @SpringBootTest with a not-mocked Servlet environment, Spring Boot auto-configures the WebTestClient for us.

Let's assume we want to write an integration test for our HTTP endpoint /api/customers/1 to ensure our clients can search for a particular customer:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class CustomerControllerIT {

  @Autowired
  private WebTestClient webTestClient;

  @Test
  void shouldReturnCustomerOne() {
    this.webTestClient
      .get()
      .uri("/api/customers/1") // the base URL is already configured for us
      .accept(MediaType.APPLICATION_JSON)
      .exchange()
      .expectStatus().isOk()
      .expectHeader().contentType(MediaType.APPLICATION_JSON)
      .expectBody()
      .jsonPath("$.customerId").isNotEmpty()
      .jsonPath("$.name").isNotEmpty();
  }
}

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)

class CustomerControllerIT {

@Autowired

private WebTestClient webTestClient;

@Test

void shouldReturnCustomerOne() {

this.webTestClient

.get()

.uri("/api/customers/1") // the base URL is already configured for us

.accept(MediaType.APPLICATION_JSON)

.exchange()

.expectStatus().isOk()

.expectHeader().contentType(MediaType.APPLICATION_JSON)

.expectBody()

.jsonPath("$.customerId").isNotEmpty()

.jsonPath("$.name").isNotEmpty();

}

The detailed usage of the WebTestClient is covered in another blog post.

Accessing OAuth2 Protected Resources with Spring WebClient

With Spring Security we get a full integration for OAuth2. Have a look at the following blog posts where I demonstrate how to enable the OAuth2 integration for the Spring WebClient:

You can find the full source code for all examples on GitHub and more detailed information about the WebClient as part of the Spring documentation.

PS: If you want to achieve the same with Jakarta EE, take a look at the JAX-RS Client or the MicroProfile RestClient.

Have fun using the Spring WebFlux WebClient,

Phil

Tweet 0

Share 0

[…] one of my recent blog posts, I presented Spring’s WebClient for RESTful communication. With Java EE we can utilize the […]

Hello Philip

I have a doubt:
I’d like to use WebClient instead of RestTemplate, but my solution is not SpringBoot but Spring default.
How do I add only WebClient dependencies and use?

rieckpil says:

January 4, 2020 at 10:28 am

Hey Fernando,

the WebClient is part of the WebFlux Spring dependency. You can pull this in your project without using Spring Boot. If you are using Maven, you can use the following import:

<dependency< <groupIdorg.springframework</groupId> <artifactId>spring-webflux</artifactId> <version>5.2.2.RELEASE</version> </dependency>

Make sure to align the version with the Spring version you have in use.

Log in to Reply

[…] Java is enough for simple use cases, it might be helpful to use Spring Framework features (e.g the WebClient, data access, etc.). With Spring Cloud Function you can achieve this and use the AWS adapter to […]

[…] Our sample project is a basic Spring Boot application. We’ll include both starters for Web and WebFlux. Hence Spring Boot autoconfigures the embedded Tomcat for us while we are able to use parts from Spring WebFlux like the WebClient. […]

[…] won’t add new features to the RestTemplate, the general recommendation is to start using the Spring WebFlux WebClient. Besides the reactive and non-blocking nature of the WebClient, you can seamlessly include it to […]

One question, Why do I get the illegal StateException: The underlying HTTP client completed without emitting a response when using the web client? When I use block it works correctly, any idea why it could be happening?

rieckpil says:

August 21, 2020 at 4:49 am

Hey Daniel,

hard to tell without seeing the actual code. Could you create a question on StackOverflow and send me the link?

Kind regards,
Philip

Log in to Reply

[…] the WebClient, Spring provides a WebTestClient for testing purposes. The API of this class is similar to the […]

[…] going to test an HTTP client class that uses the Spring WebFlux WebClient to fetch a random quote from a remote […]

Setup and Examples for the Spring WebFlux WebClient

Create and Configure the WebClient

HTTP GET Request Example With Spring WebClient

Handle Different HTTP Response Codes

HTTP GET Request Example With Spring WebClient

Retry Configuration On Failure

Configure Filters for the Spring WebClient

Writing Tests For Classes Using the WebClient

Integration Testing With the WebTestClient

Accessing OAuth2 Protected Resources with Spring WebClient

Spring Boot Testing Starter Course

Spring Boot Testing Advanced & Deep-Dive Course

Quicklinks

Recently Published