Spring WebClient is a non-blocking, reactive client to perform HTTP requests, a part of Spring WebFlux framework

In this tutorial, you will learn how to use WebClient and take a look at the difference between its exchange() and retrieve() methods

What you'll need

  • JDK 8+ or OpenJDK 8+
  • Maven 3+

Add WebClient into your project

As WebClient is a part of Spring WebFlux, you can add it to the pom.xml or build.gradle file of your project via the spring-webflux dependency

In the Spring Boot project, you can add spring-boot-starter-webflux instead. The library versions can be omitted as it is resolved by the parent pom provided by Spring Boot


Create a WebClient instance

You can use either create(), create(baseUrl) or builder() factory methods of WebClient interface to create an instance

  • The create(baseUrl) method is more practical than create() method as it is handy and you can provide the default base URL for subsequence requests later
WebClient webClient1 = WebClient.create();  
WebClient webClient2 = WebClient.create("http://localhost:8080");  
  • Use builder() if you'd like to set the default headers and cookies
WebClient webClient = WebClient.builder()  
    .defaultHeader(HttpHeaders.USER_AGENT, "Hello Koding")
    .defaultCookie("cookie name", "cookie value")

Build an HTTP request with WebClient

You can build an HTTP request with WebClient by following these steps

  • Start with either get(), post(), put(), patch(), delete(), options() or head() in coressponding with HTTP GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD request respectively

  • Build request URI with uri(String) or uri(uriBuilder) if you'd like to send path variables or query parameters

  • Add custom cookies and request headers with cookies() and headers()

  • Perform the request and get the response with retrieve() or exchange()

  • Convert the response to Mono or Flux with bodyToMono() or bodyToFlux()

The following gives you an example on building a GET request

public void buildAnHttpRequest() {  
    WebClient webClient = WebClient.create("http://localhost:8080");

    Mono<String> result = webClient.get()
        .uri(uriBuilder -> uriBuilder
            .queryParam("name", "Koding")

        .isEqualTo("Hello, Koding!");

Exchange vs Retrieve in WebClient

The retrieve() method is a shortcut to using exchange(). Uses exchange() if you'd like to check and handle response error

The following gives you another version of the above example by using exchange()

public void exchange() {  
    WebClient webClient = WebClient.create("http://localhost:8080");

    Mono<ClientResponse> result = webClient.get()
        .uri(uriBuilder -> uriBuilder
            .queryParam("name", "Koding")

    assertThat(result.flatMap(res -> res.bodyToMono(String.class)).block())
        .isEqualTo("Hello, Koding!");


In this tutorial, we learned how to create a WebClient instance, and use it to build and execute an HTTP request. You can find the full source code as below