Getting Query String Parameters from HttpServletRequest

1. Introduction

One of the most important capabilities of backend HTTP API development is the ability to resolve request query parameters passed by the frontend.

In this tutorial, we’ll introduce several ways to get the query parameters from HttpServletRequest directly, and some concise ways provided by Spring MVC.

2. Methods in HttpServletRequest

First, let’s see the parameter-related methods provided by HttpServletRequest.

2.1. HttpServletRequest#getQueryString()

This example shows what we can get from the URL directly by invoking the method HttpServletRequest#getQueryString():

@GetMapping("/api/byGetQueryString")
public String byGetQueryString(HttpServletRequest request) {
    return request.getQueryString();
}

When we send a GET request using curl with several parameters to this API, the method getQueryString() just returns all the characters after ‘?’:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetQueryString?username=bob&roles=admin&roles=stuff'
username=bob&roles=admin&roles=stuff

Note that if we change @GetMapping to @RequestMapping, it will return the same response when we send the request by POST/PUT/PATCH/DELETE HTTP method. This means HttpServletRequest will always obtain the query string no matter what the HTTP method is. So, we can just focus on the GET request in this tutorial. To simplify our demonstration of the methods provided by HttpServletRequest, we’ll also use the same request parameters in each of the following examples.

2.2. HttpServletRequest#getParameter(String)

To simplify parameter resolution, the HttpServletRequest provides a method getParameter to get the value by parameter name:

@GetMapping("/api/byGetParameter")
public String byGetParameter(HttpServletRequest request) {
    String username = request.getParameter("username");
    return "username:" + username;
}

When we send a GET request with a query string of username=bob, the call getParameter(“username”) returns bob.

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetParameter?username=bob&roles=admin&roles=stuff'
username:bob

2.3. HttpServletRequest#getParameterValues(String)

The method getParameterValues acts similar to the getParameter method, but it returns a String[] instead of a String. This is due to the HTTP specification allowing to pass multiple parameters with the same name.

@GetMapping("/api/byGetParameterValues")
public String byGetParameterValues(HttpServletRequest request) {
    String[] roles = request.getParameterValues("roles");
    return "roles:" + Arrays.toString(roles);
}

So when we pass the value with parameter roles twice, we should get two values in the array:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetParameterValues?username=bob&roles=admin&roles=stuff'
roles:[admin, stuff]

2.4. HttpServletRequest#getParameterMap()

Let’s say we have the following UserDto POJO as part of the following JSON API examples:

public class UserDto {
    private String username;
    private List<String> roles;
    // standard getter/setters...
}

As we can see, it is possible to have several different parameter names with one or more values. For these cases, HttpServletRequest provides another method, getParameterMap(), which returns a Map<String, String[]>. This method allows us to get the parameter values using a Map.

@GetMapping("/api/byGetParameterMap")
public UserDto byGetParameterMap(HttpServletRequest request) {
    Map parameterMap = request.getParameterMap();
    String[] usernames = parameterMap.get("username");
    String[] roles = parameterMap.get("roles");
    UserDto userDto = new UserDto();
    userDto.setUsername(usernames[0]);
    userDto.setRoles(Arrays.asList(roles));
    return userDto;
}

We’ll get a JSON response for this example:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetParameterMap?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

3. Get Parameters with Spring MVC

Let’s see how Spring MVC improves the coding experience when resolving the query string.

3.1. Parameter Name

With the Spring MVC framework, we do not have to manually resolve the parameters ourselves using the HttpServletRequest directly. For the first case, we define a method with two parameters with the query parameter names username and roles and remove the usage of HttpServletRequest, which is handled by Spring MVC.

@GetMapping("/api/byParameterName")
public UserDto byParameterName(String username, String[] roles) {
    UserDto userDto = new UserDto();
    userDto.setUsername(username);
    userDto.setRoles(Arrays.asList(roles));
    return userDto;
}

This will return the same result as the last example since we use the same model:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byParameterName?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

3.2. @RequestParam

If the HTTP query parameter name and Java method parameter name are different, or if the method parameter names won’t be retained in the compiled bytecode, we can configure annotation @RequestParam on the method parameter name for this situation.

In our case, we use @RequestParam(“username”) and @RequestParam(“roles”) as follows:

@GetMapping("/api/byAnnoRequestParam")
public UserDto byAnnoRequestParam(@RequestParam("username") String var1, @RequestParam("roles") List<String> var2) {
    UserDto userDto = new UserDto();
    userDto.setUsername(var1);
    userDto.setRoles(var2);
    return userDto;
}

and test it:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byAnnoRequestParam?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

3.3. POJO

More simply, we can use a POJO as the parameter type directly:

@GetMapping("/api/byPojo")
public UserDto byPojo(UserDto userDto) {
    return userDto;
}

Spring MVC can resolve the parameters, create the POJO instance, and fill it with the required parameters automatically.

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byPojo?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

Finally, we check with a unit test to make sure that the last four methods provide exactly the same features.

@ParameterizedTest
@CsvSource(textBlock = """
    /api/byGetParameterMap
    /api/byParameterName
    /api/byAnnoRequestParam
    /api/byPojo
    """)
public void whenPassParameters_thenReturnResolvedModel(String path) throws Exception {
    this.mockMvc.perform(get(path + "?username=bob&roles=admin&roles=stuff"))
      .andExpect(status().isOk())
      .andExpect(jsonPath("$.username").value("bob"))
      .andExpect(jsonPath("$.roles").value(containsInRelativeOrder("admin", "stuff")));
}

4. Conclusion

In this article, we have introduced how to get the parameters from a HttpServletRequest using Spring MVC. From these examples, we can see that a lot of code can be reduced when using Spring MVC to parse parameters.

As usual, all code snippets presented in this article are available over on GitHub.