@RequestParam Example in Spring Boot REST

In this Spring Boot REST tutorial, you will learn how to use the @RequestParam annotation to read the URL Query request parameters in your Spring Boot Web Services application. I also include a video tutorial here, so you can see it in action.

To learn how to read request parameters from the URL request path, read the @PathParam example tutorial.

Let’s assume we have the following URL to your Web Service endpoint.

http://localhost:8080/api/users?page=1&limit=50

If we break the above URL down into smaller parts, then we will see that:

HTTP – is the protocol being used,
localhost – is the domain name,
8080 – is the port number,
api – is the root path of your web services application,
users – is most likely the @Path value of your Root Resource class and,
page – is the URL Query parameter which we can read with @RequestParam annotation,
limit – is the URL Query parameter which we can also read with @RequestParam annotation.

Let’s look at how we can read the above request URL query string parameters with the @RequestParam annotation.

Read Request URL Query Parameters with @RequestParam

Let’s say we have the below @RestController class with a method that reads the two URL Query string request parameters which are mentioned in the URL above.

To read the request parameter from the URL Query string, use the @RequestParam annotation in the following way:

@RequestParam(value = "page", defaultValue = "0")

Below is an example of the @RestController class:

@RestController
@RequestMapping("users")
public class UserController {

    @Autowired
    UserService userService;

    @GetMapping(produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
    public List<UserRest> getUsers(@RequestParam(value = "page", defaultValue = "0") int page,
            @RequestParam(value = "limit", defaultValue = "30") int limit) {
       
          List<UserRest> returnValue = new ArrayList<>();

        List<UserDto> users = userService.getUsers(page, limit);

        for (UserDto userDto : users) {
            UserRest userModel = new UserRest();
            BeanUtils.copyProperties(userDto, userModel);
            returnValue.add(userModel);
        }

        return returnValue;
    }
}

Please notice how the @RequestParam annotation is used in the method signature to read the two URL Query string request parameters and make them available as method arguments.

@RequestParam Default Value

In the code example above, I have provided a default value to be used if the request parameter is not provided. Below is a simpler example demonstrating how to provide a default value to the query string request parameters.

@GetMapping()
public String getUsers(@RequestParam(value = "page", defaultValue = "1") int page,
           @RequestParam(value = "limit", defaultValue = "30") int limit)
{
 return "get users was called. </br> Page = " + page  + " and limit = " +  limit;
}

Optional or Required Request Parameters

Making a Request Parameter Optional

Provide a default value by using the defaultValue = “<value here>” or,
Use required=false for a @RequestParam annotation.

If you provide a defaultValue = “<value here>” for a request parameter as in the example above, then this request parameter becomes optional, and the user might not include it in the request. In this case, if the request parameter is not included in the URL, its value will default to the value provided by the defaultValue. Or you can use the required=false with the @RequestParam annotation.

Note that required=false works well only with String datatypes.

@GetMapping()
public String getUsers(@RequestParam(value = "sort", required=false) String sort)
{

 return "get users was called with Sort option = " + sort;
}

Making a Request Parameter Required

Do not use the defaultValue = “<value here>” or,
Use required=true for a @RequestParam annotation.

If the @RequestParam annotation is used and the default value is not provided, then this request parameter becomes required by default. However, if you want to explicitly specify that a specific request parameter is required and must be provided, then use the required=true as it is in the example below.

@GetMapping()
public String getUsers(@RequestParam(value = "sort", required = true) String sort,
           @RequestParam(value = "limit", defaultValue = "30") int limit)
{
 return "get users was called with sort option = " + sort;
}

Reading Query String Request Parameters – Video Tutorial

Making Query String Request Parameters Optional – Video Tutorial

I hope this short tutorial on how to read request parameters from URL query string in your Spring Boot application was helpful to you.

If you are interested in learning more about the Spring Boot REST, please check the video courses below; hopefully, one of them will be just what you were looking for.