Spring @RequestParam Annotation

In this post, we will explore the Spring’s @RequestParam annotation. This Spring MVC annotation shows that a method parameter should bound to a web request parameter.


1. Spring @RequestParam 

The @RequestParam annotation binds the web request parameter to a controller method. In simple words, we can use the @RequestParam annotation to get values from query parameters and from parameters. Let’s take a closer looks at some important points:


2. The @RequestParam Mapping

Let’s create a simple controller to understand this annotation more:

 public String sayHello(@RequestParam String name) {
  return "Hello "+name+"!!!";

In above example, we are extracting the query parameter using the @RequestParam annotation. This is how our request looks like:

curl -i -H "Accept: application/json" -H "Content-Type: application/json" http://localhost:8080/greeting?name=javadevjournal

Above request get the following response from the controller: Hello javadevjournal!!!


3. The Parameter Name

There are few situations when we want to set the name of the parameter and do not want to use the default one (part of the request parameter). Let’s take a simple use case when we like to store the email address in the Id field.

  public String getUser(@RequestParam(name = "email") String id) {
   return "It seems we have a record for email " + id;

We can also do @RequestParam(name = “email”) or just @RequestParam(“email”).


4. Default Value for Request Parameter

This annotation allows us to set the default value for the request parameter. This is useful for sending a default response for empty parameter.

 public String defaultValueExample(@RequestParam(defaultValue = "Anonymous user") String name) {
  return "Hello " + name + "!!!";

Let’s see what is the outcome of the following requests:

output: Hello Anonymous user!!!

Let’s see how this reacts when we send name as part of request:

http://localhost:8080/default-value?name=Java Development Journal
Output: Hello Java Development Journal!!!


5. Optional Request Parameter

By default parameter annotated with @RequestParam are required. This means that client need to pass information as part of the request else API will throw an error. Let’s see this in the action for better clarity:

 public String sayHello(@RequestParam String name) {
  return "Hello "+name+"!!!";

If we send a request without passing the “name” in the request, we will get an error back from the service.

curl -i -H "Accept: application/json" -H "Content-Type: application/json" http://localhost:8080/greeting
HTTP/1.1 400 
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Sun, 16 Dec 2018 01:39:21 GMT
Connection: close

   "error":"Bad Request",
   "message":"Required String parameter 'name' is not present",

This annotation allows us to mark this parameter as “optional” with the required attribute. Let’s change the above example to see this in action:

 public String optional(@RequestParam(required = false) String name) {
  return getGreeting(name);

Let’s see what is the response from the controller method:

curl -i -H "Accept: application/json" -H "Content-Type: application/json" http://localhost:8080/optional
HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8
Content-Length: 16
Date: Sun, 16 Dec 2018 01:46:33 GMT
Hello Stranger!!


6. Multi Value Parameter

The RequestParam annotation can be map multiple values in a list. Let’s take an example where we like to send multiple values as comma-separated values to the method and like to store these values as a List. Spring MVC will maps comma-separated values in the list. Let’s understand this by an example:

public String getProducts(@RequestParam List < String > id) {
   return "Products: " + id;

Here is the output for our requests:

curl -i -H "Accept: application/json" -H "Content-Type: application/json" http://localhost:8080/products?id=12,13,14
HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8
Content-Length: 22
Date: Sun, 16 Dec 2018 02:01:46 GMT
Products: [12, 13, 14]
Output: Products: [12, 13]


7. @RequestParam vs @PathVariable

I can use both annotation to get values from the request URI. Let’s see the difference between @RequestParam and @PathVariable?

  • @PathVariable is to obtain placeholder from the URI.
  • @RequestParam is to obtain a parameter from the URI

This is how @PathVariable annotation looks like:

public String getProduct(@PathVariable(value = "code") String code,
 @RequestParam(value = "category", required = false) String category) {



In this article, we learned what is @RequestParam annotations and what are the different features of this annotation. Full source code is available on GitHub.