Add URI Parameters to Spring WebClient Requests

Examples of Adding Requests Parameters like URI Path Parameters and Query Parameters in Spring WebClient requests.


Spring WebClient is a reactive and non-blocking client for making HTTP requests. This client is part of Spring WebFlux library and as per the recent updates, it is going to replace the traditional RestTemplate client. In contrast to the RestTemplate, the WebClient offers a flexibility of using builder pattern to build and execute requests. Also the WebClient allow blocking or a non-blocking style of request execution.

In this tutorial, we will learn passing URI Parameters (path parameters, and query parameters) in a WebClient Requests. Before we do that, let’s understand what are URI Parameters and examples of different types of parameters.

URI Parameters in Requests

The request URI parameters help identifying a particular resources on the server, specify certain filters on the response, or pass some information to the server. There are mainly three different types of request parameters – Path Parameters, Query Parameters, and Header Parameters. However, this tutorial focuses on Request URI parameters, which are path parameters or path variables and query parameters.

Path Parameters

The Path Parameters are a type of request parameters, which appear on the path of a Request URI. They are also known as Path Variables or Path Segments. They help to bind the request to a certain resource(s).

For example,

  • GET /students
  • GET /students/{studentId}
  • GET /students/{studentId}/assignments/{assignmentId}

The first endpoint maps to all students on the server. Hence the server should return all students in the response. However, the second endpoint has got a path variable to identify a particular student. Similarly, the third endpoint has nested path variables, which maps to a particular assignment of a particular student.

Query Parameters

The Query Parameters or Query String Parameters are key and value pairs separated by an ampersand (&) and they appear at the end of a URL, after a question mark (?). The Query Parameters are an extension to Path variables and are usually used to put additional filters on the resource.

For example,

  • GET /students?firstName=Jon&year=1995
  • GET /students?year=1995&year=1996&year=1997

In the first one the endpoint finds students by firstName and year. Similarly, the second one returns students by array of years.

In the next sections we will see How to pass Path Variables and Query Strings using Spring WebFlux WebClient.

Path Parameters in WebClient

Let’s use WebClient to access a resource endpoint without passing any path variable or parameter.

WebClient.create("http://localhost:8080") .get() .uri("/students") .retrieve() .bodyToFlux(Student.class);
Code language: Java (java)

This returns a Flux of all students. Now, let’s add a path variable to narrow down the request to a specific resource.

Path Parameter using String Concatenation

The simplest and the most basic method of adding a path parameter or URI component to a request URI is to use String concatenation.

WebClient.create("http://localhost:8080") .get() .uri("/students/" + studentId) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

Path Parameter using UriBuilder

Alternatively, we can use Spring UriBuilder to build a URI with a Path Variable or Path Segment.

WebClient.create("http://localhost:8080") .get() .uri(uriBuilder -> uriBuilder .path("/student/{studentId}") .build(studentId)) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

As shown here, the UriBuilder function replaces the {studentId} token with the value provided in the build() method.

Similarly, we can use the UriBuilder to build a URI having multiple path variables that accesses a nested resource on the server.

WebClient.create("http://localhost:8080") .get() .uri(uriBuilder -> uriBuilder .path("/student/{studentId}/assignments/{assignmentId}") .build(studentId, assignmentId)) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

The example shows executing an endpoint with two path parameters. We have provided two values to the build() method. The UriBuilder sequentially replace them in the URI from left to right.

Path Parameter using UriTemplate

Similarly, we can use Spring UriTemplate to build a URI with zero or more path parameters. Using it, we can create a URI template once and use it with different values to access different resources.

Firstly, we will create an instance of UriTemplate by providing a templated URI in the form of string.

UriTemplate uriTemplate = new UriTemplate("/student/{studentId}/assignments/{assignmentId}");
Code language: Java (java)

Next, we can use the UriTempalte in WebFlux WebClient and provide path parameters.

WebClient.create("http://localhost:8080") .get() .uri(uriTemplate.expand(studentId, assignmentId)) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

Note that, every time we invoke the expand method a new URI instance is returned. That means, we can reuse the same URI Template to make different requests with different path variable values.

Query Parameters in WebClient

Similar to the path parameters we can use String concatenation or UriTemplate to attach query parameters. However, using the UriBuilder to pass query parameters is slightly different than that of path variables. Thus, we will focus on using UriBuilder.

Single Value

In order to pass single value query parameters, create a path of the base resource URI and then use queryParam() method to append key value pairs.

String firstName = "Jon"; String year = "1996"; WebClient.create("http://localhost:8080") .get() .uri(uriBuilder -> uriBuilder.path("/students") .queryParam("firstName", firstName) .queryParam("year", year) .build()) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

The final URL that the WebClient executes will be


Multiple Values or Arrays

If a query parameter in a URI has multiple values then the parameter appears multiple times with different values. To do that with UriBuilder, we can pass all those values into the queryParam() method.

WebClient.create("http://localhost:8080") .get() .uri(uriBuilder -> uriBuilder.path("/students") .queryParam("year", 1995, 1996, 1997) .build()) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

The example shows passing an array as a query String in WebClient. The final URL looks like this.


Comma Separated Value

Lastly, to send a query parameter having comma separated values, we can join multiple String values with comma.

WebClient.create("http://localhost:8080") .get() .uri(uriBuilder -> uriBuilder.path("/students") .queryParam("year", String.join(",", "1995", "1996", "1997")) .build()) .retrieve() .bodyToMono(Student.class);
Code language: Java (java)

The final URL looks as shown in the next snippet.



This tutorial covered How to pass URI Parameters in Spring WebFlux WebClient Requests. Which focused on passing Path Parameters and Query Parameters.

To summarize, we started with an introduction to request URI parameters – path parameters or path segments and query strings with examples. Then we learned how to use String concatenation, UriBuilder, and UriTemplate to add path parameters in WebClient. Lastly, we learned passing single value query parameters, multi value query parameters, and query parameters with comma separated values.