Sending HTTP requests using Spring WebClient (2023)

In Spring 5, Spring received a reactive web framework: Spring WebFlux. This is designed to co-exist with existing Spring Web MVC APIs, but with support for non-blocking themes. With WebFlux, you can build asynchronous web applications using reactive flows and functional APIs to better support concurrency and scaling.

As part of this, Spring 5 introduced the newweb clientAPI, replaces the existing oneRestTemplateClient. To useweb clientYou can make synchronous or asynchronous HTTP requests with a functional fluent API that directly integrates with your existing Spring setup and responsive WebFlux framework.

In this article, we'll first look at how you can start making simple GET and POST requests to an API.web clientnow, and then discuss how to takeweb clientalso for extended use in extensive production applications.

How to make a GET request withweb client

Let's start with a simple GET request to read content from a server or API.

To get started, you'll first need to add some dependencies to your project if you don't already have them. If you use Spring Boot, you can usespring-boot-starter-webflux, or alternatively you can installspring-webfluxeReator-NettyImmediately.

In springweb clientThe API is intended to be used in addition to an existing asynchronous HTTP client library. In most cases it is Netty Reactor, but you can also use Jetty Reactive HttpClient or Apache HttpComponents or integrate others by creating a custom connector.

Once installed, you can send your first GET requestweb client:

WebClient-Client=web client.cry();web client.response specificationresponse specification=Client.to receive() .uri("http://beispiel.com") .to remember();

A lot is happening here:

• we created aweb clientexample
• We define an order with theweb clientInstance, specifying the request method (GET) and URI
• We finish the configuration of the request and get aresponse specification

That's all it takes to submit a request, but it's important to note that no requests have been submitted at this time!As a reactive API, the request isn't actually sent until something tries to read it or waits for the response.

How do we do it?

Handling an HTTP response withweb client

After making a request, we usually want to read the contents of the response.

In the example above, we call.to remember()get oneresponse specificationfor an order. This is an asynchronous operation that doesn't block or wait for the request itself, which means the request is still pending on the next line, so we can't access the response details yet.

Before we can get any value out of this async operation, you need to understand it.FloweMonotypes of reactors.

Flow

ONEFlowrepresents a flow of items. It is a sequence that will asynchronously output any number of items (0 or more) into the future before completing (either successfully or with an error).

In reactive programming, this is our bread and butter. ONEFlowit's a stream that we can transform (giving us a new stream of transformed events), buffer into a list, reduce to a single value, concatenate with other streams, and merge or block to wait for a value.

Mono

A mono is a specific but very common type ofFlow: oneFlowwhich asynchronously returns 0 or 1 results before completing.

In practice, it is similar to that of JavaSupplementaryFuture: Represents a single future value.

If you want more information about this, have a look.Spring's own docsthat further explain reactive types and their relationship to traditional Java types.

read the body

To read the response text, we need aMono(that is, an asynchronous future value) to the response content. We then need to somehow unpack this to trigger the request and get the content from the response body itself once it's available.

There are several ways to unpack an async value. First, let's use the simplest traditional option, blocking to wait for the data to arrive:

String responseBody=response specification.body for mono(line.class).Quadra();

This gives us a string containing the raw text of the response. You can pass different classes here to automatically parse the content into a suitable format or use aFlowhere for a stream of response parts (from an event-driven API, for example), but we'll get to that in a moment.

Please note that we do not check the status here. if we use.to remember(), the client will automatically check the status code for us and provide a reasonable default by throwing an error for any 4xx or 5xx response. We'll also talk about custom status checks and error handling later.

How to send a complex POST request withweb client

We've seen how to send a very basic GET request, but what if we want to send something more advanced?

Let's look at a more complex example:

MultiValueMap<line,line>body values= Neubound MultiValueMap<>();body values.Add("Key", "Wert");body values.Add("another key", "other value");string response=Client.Post() .uri(NeuURI("https://httpbin.org/post")) .Header("To allow", "Inhaber MY_SECRET_TOKEN") .content type(media type.APPLICATION_FORM_URLENCODED) .to accept(media type.APPLICATION_JSON) .body(body inserter.fromFormData(body values)) .to remember() .body for mono(line.class) .Quadra();

as we can see hereweb clientallows us to configure headers using dedicated methods for common cases (.contentType(Type)) or generic keys and values ​​(.header(chave, valor)).

In general it is preferable to use dedicated methods as their tighter typing helps us to provide the correct values ​​and they include runtime validation to catch various invalid settings as well.

This example also shows how to add a body. Here are some options:

• we can call.Body()commonbody inserter, which creates text content for nodes from form values, multipart values, data buffers, or other codeable types.
• we can call.Body()commonFlow(including aMono) that can asynchronously stream content to build the request body.
• we can call.bodyValue(valor)to supply a string or other directly encoded value.

Each of them has different use cases. Most developers unfamiliar with reactive flows won't find the Flux API useful at first, but as you invest more in the reactive ecosystem, asynchronous streams of streamed data like this will feel more natural.

How to take the springweb clientin production

The above should be enough to get you started asking basic queries and reading the answers, but there are a few more topics we need to cover if you want to build advanced applications around them.

Read response headers

So far, we've focused on reading the response body and ignoring the headers. Most of the time that's fine, and the important headers are handled for us, but you'll find that many APIs include valuable metadata in their response headers, not just the body.

These data are easily available on theweb clientAPI also with the.toEntity()API that gives us aresponse entity, wrapped in aMono.

This allows us to examine the response headers:

response entity<line>reply=Client.to receive() // ... .to remember() .to entity(line.class) .Quadra();HttpHeaders responseHeaders=reply.getHeader();List<line>HeaderWert=ResponseHeader.to receive("header-name");

Analyzing response bodies

In the examples above, we treat responses as simple strings, but Spring can also automatically decompose them into many supertypes for you by simply specifying a more specific type when reading the response, like this:

Mono<Person>reply=Client.Post() // ... .to remember() .body for mono(Person.class)

Which classes can be converted depends on theHttpMessageReaderthat are present. By default, supported formats include:

• Conversion of each answer toline,Byte[],ByteBuffer,data bufferorResource
• Conversion ofapplication/x-www-form-urlencodedanswers insideMultiValueMap<String,String>>
• Conversion ofmultipart/form-dataanswers insideMultiValueMap<string, part>
• Deserializing JSON data using Jackson, if available
• Deserialization of XML data using Jackson's XML extension or JAXB, if available

This can also use the patternHttpMessageConverterConfiguration registered in your Spring application, allowing the message converters to be shared between the code of your WebMVC or WebFlux server and yoursweb clientinstances. If you use Spring Boot, you can usethe preconfigured WebClient.Builder instanceto set this up automatically.

For more details have a look atSpring WebFlux-Codec-Documentation.

Manually manage response status

by default.to remember()will check the error status for you. This is fine for simple cases, but you'll likely encounter many REST APIs that encode more detailed success information into their status codes (e.g., returning 201 or 202 values) or APIs where you want custom handling to add some bug status .

You can read the status ofresponse entity, as we did for headers, but this is only useful for accepted statuses, because in that case error statuses throw an error before we get the entity.

To handle these states ourselves, we need to add aonStatushandlers. This handler can match certain statuses and return amono<play>(to track the specific error) ormonkey.read()to prevent this status from being treated as an error.

It works like this:

Response Entity Response=Client.to receive() // ... .to remember() // Don't treat 401 responses as errors: .onStatus(Status->Status.Wert() ==401,customer response->Mono.File() ) .to entity(line.class) .Quadra();// Check and handle relevant status codes manually:What if (reply.getStatusCodeValue() ==401) { // ...} anders { // ...}

Make fully asynchronous requests

So far we called.Quadra()block the thread completely for each response to wait for the response to arrive.

Within a traditional tightly threaded architecture, this might naturally fit in, but in a non-blocking design, we should avoid these types of blocking operations whenever possible.

Alternatively, we can handle requests by weaving transformations around ourMonoorFlowValues ​​to process and match values ​​as they are returned and then pass themFlow-Wrap the values ​​in other non-blocking APIs, all fully asynchronous.

This is not the space to fully explain this paradigm or WebFlux from the beginning, but an exampleweb clientit can look like this:

@GetMapping("/User ID}")PrivateMono<from the user> getUserById(@PathVariableString-ID) { // Loads some user data asynchronously, for example from a database:Mono<BaseUserInfo>user information=getBaseUserInfo(I could); // Load user data with separate API WebClient:Mono<user signature>User Signature=Client.to receive() .uri("http://subscription-service/api/user/" +I could) .to remember() .body for mono(user signature.class); // Combine the monos: when both are ready, take these // Data from each and combine them into a user object.Mono<from the user>from the user=user information.zipMit(User Signature) .Map((tupel) -> Neufrom the user(tupel.getT1(),tupel.getT2()); // The mono resulting from the combined data can be returned immediately, // without waiting or blocking, and WebFlux sends // the response later, when all the data is ready: Returnsfrom the user;}

Testing with SpringWebTestClient

In addition toweb client, Spring 5 includesWebTestClient, which offers an interface very similar to theweb client, but designed for convenient testing of server terminals.

We can configure this by creating aWebTestClientlinked to a server and sending actual requests over HTTP, or one linked to a singleRules,RouterFunktionorWebHandlerNameto run integration tests with simulated request and response objects.

It looks like this:

// Connect to a real server via HTTP:WebTestClient-Client=WebTestClient.bindToServer() .baseUrl("http://localhost:8000") .build up();// Or connect to a single WebHandler using dummy objects:WebTestClient-Client=WebTestClient.bindToWebHandler(handler) .build up();

After creating a WebTestClient, we can define requests like any otherweb client.

To send the request and check the result, we call.Exchange()and then use the assertion methods available there:

Client.to receive() .uri("/api/user/123") .Exchange() .expected state().was not found(); // Confirm this is a 404 response

There are a variety of assertion methods for checking response status, headers, and body - seeo JavaDocfor the complete list.

After providing yourweb clientcode, you need to be able to debug it. HTTP requests are often the focal point of complex interactions and can fail in a number of interesting ways. It's helpful to see the requests and responses your customer is working with to understand what your system is doing, and entering your own data or bugs can be a powerful technique for manual testing.

For that you can useHTTP Toolkit, an open source, cross-platform tool that can capture traffic from a variety of Java HTTP clients and that includes special integration to automatically intercept Springweb client.

After installing the HTTP toolkit, the next step is to intercept Java HTTP traffic. To do this, you can:

• In the HTTP Toolkit, click the Fresh Terminal button to open a terminal and launch your application from there; or
• Start your application normally and click the Attach to JVM button in the HTTP Toolkit to attach it to the already running JVM

After intercepting your traffic, you can inspect each request and response sent by your application from the HTTP Toolkit's Preview page:


You can also add mock page rules to interactively simulate HTTP responses or breakpoint requests or inject errors such as connection errors and timeouts.

Conclusion

In this article, we've seen everything you need to get started with Spring.web client🇧🇷 WebFlux andweb clientthey're mature and powerful APIs that still have a lot to offer beyond the classic Spring features, so try them out in your app today.