@RequestParam

Think about ordering food at a canteen. You say, "One masala dosa, less spicy, with extra chutney." The dish is the main request. "Less spicy" and "extra chutney" are small extra choices that change how the dish is made. Some choices you must make, and some you can skip.

A web address works like that too. After the question mark in an address like /products?category=phone, the extra choices travel as query parameters. This topic shows how @RequestParam reads them in Spring Boot.

What is @RequestParam?

A query string is the part of a URL after the ?. It is a list of name=value pairs joined with &.

text
/api/products
   ?category=phone
   &page=1

Here the first pair is category=phone and the second is page=1. Each pair becomes a request parameter, and your method can read it by name. The order of the pairs does not matter.

@RequestParam gives you these settings.

• required: is the parameter compulsory? The default is true.
• defaultValue: the value to use when the parameter is missing or empty.
• name (or value): the parameter name, if it differs from the Java variable.

Spring converts the text to the type you write. An int, a boolean, a List<String> and an Optional<String> all work. If the conversion fails, the client gets 400 Bad Request.

Why is it used?

Some data does not belong in the path. Filters, search words, page numbers and sort order are all optional extras. A query parameter fits them well.

• Optional filters. /products shows everything, and /products?category=phone narrows it down. Same endpoint, different questions.
• Search. A search word like ?q=cable is one value that changes with every call.
• Paging. ?page=2&size=10 lets a client walk through long lists.
• Defaults. You choose what happens when the client says nothing. A shop can show the first page of results, sorted by name, without the client asking for it.
• Simple testing. You can try a query parameter by typing it in the browser address bar. There is no JSON to write.

How it works

When a request arrives, Spring reads each pair from the query string and offers them to your method by name.

text
GET /api/products?category=phone

        |
        v
+---------------------------+
| Parse query string        |
| category = "phone"        |
+---------------------------+
        |
        v
+---------------------------+
| Bind to method parameters |
| @RequestParam category    |
| @RequestParam maxPrice    |
+---------------------------+

The first parameter finds its value in the query string. The second one, maxPrice, is missing, so Spring looks at its settings next.

text
Is the parameter present?
     |            |
    YES           NO
     |            |
     v            v
 convert      Has defaultValue?
 to type       |          |
     |        YES         NO
     v         |          |
 method runs   v          v
          use default  required?
                        |     |
                       YES    NO
                        |     |
                        v     v
                    400 error null

This is the whole decision. A present value is converted. A missing value falls back to defaultValue if there is one. Without a default, a required parameter gives a 400 error, and an optional one becomes null.

Real-Life Example

Think of a shopping app on your phone. You open the phone section and set "under 20,000 rupees" and "brand: any". The app sends those choices, and shows the first page of results. If you do not touch any filter, it shows all phones. The filters are optional, so the shop has defaults. But if you press "search" with an empty box, the app asks you to type a word. That is a required parameter. It cannot search for nothing.

text
techmart/
├─ pom.xml
└─ src/main/java/
   └─ com/techmart/shop/
      ├─ ShopApplication.java
      └─ ProductController.java

xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>

    <groupId>com.techmart</groupId>
    <artifactId>shop</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

java
package com.techmart.shop;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ShopApplication {

    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }
}

java
package com.techmart.shop;

import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    record Product(int id, String name, String category, int priceInRupees) {}

    private final List<Product> products = List.of(
            new Product(1, "Nova X Phone", "phone", 18000),
            new Product(2, "Zen Buds", "audio", 2500),
            new Product(3, "Pixel Lite Phone", "phone", 26000),
            new Product(4, "USB-C Cable", "accessory", 400),
            new Product(5, "Bass Speaker", "audio", 3500));

    @GetMapping
    public List<Product> search(
            @RequestParam(required = false) String category,
            @RequestParam(defaultValue = "100000") int maxPrice,
            @RequestParam(defaultValue = "0") int page) {
        return products.stream()
                .filter(p -> category == null || p.category().equals(category))
                .filter(p -> p.priceInRupees() <= maxPrice)
                .skip(page * 2L)
                .limit(2)
                .toList();
    }

    @GetMapping("/find")
    public String find(@RequestParam("q") String query) {
        return "Searching for " + query;
    }

    @GetMapping("/compare")
    public List<Product> compare(@RequestParam List<Integer> ids) {
        return products.stream().filter(p -> ids.contains(p.id())).toList();
    }
}

bash
mvn spring-boot:run
curl "localhost:8080/api/products?category=phone"
curl "localhost:8080/api/products?maxPrice=3000&page=0"
curl "localhost:8080/api/products/find?q=cable"
curl "localhost:8080/api/products/compare?ids=1,4"

json
[
  {
    "id": 1,
    "name": "Nova X Phone",
    "category": "phone",
    "priceInRupees": 18000
  },
  {
    "id": 3,
    "name": "Pixel Lite Phone",
    "category": "phone",
    "priceInRupees": 26000
  }
]

json
[
  {
    "id": 2,
    "name": "Zen Buds",
    "category": "audio",
    "priceInRupees": 2500
  },
  {
    "id": 4,
    "name": "USB-C Cable",
    "category": "accessory",
    "priceInRupees": 400
  }
]

text
Searching for cable

json
[
  {
    "id": 1,
    "name": "Nova X Phone",
    "category": "phone",
    "priceInRupees": 18000
  },
  {
    "id": 4,
    "name": "USB-C Cable",
    "category": "accessory",
    "priceInRupees": 400
  }
]

bash
curl -s -o /dev/null -w "%{http_code}\n" "localhost:8080/api/products/find"
curl -s -o /dev/null -w "%{http_code}\n" "localhost:8080/api/products?maxPrice=abc"
curl "localhost:8080/api/products?page=9"

text
400
400
[]

Code Explained

• @RequestParam(required = false) String category is optional. If the client leaves it out, the value is null, and our filter lets every product pass.
• defaultValue = "100000" is used when maxPrice is missing. It is written as text and converted to int. A parameter with a default is never treated as missing.
• page defaults to 0. The code skips page * 2 items and returns two, so each page has at most two products.
• @RequestParam("q") String query names the parameter. The client sends q, and the Java variable is query.
• Without required = false or a default, q is required. A call without it answers 400.
• List<Integer> ids takes a comma-separated list. ids=1,4 becomes a list of two numbers.
• maxPrice=abc cannot become an int, so Spring answers 400.

Query Parameter Settings at a Glance

Common Mistakes

• Forgetting quotes in curl. Without quotes, the shell reads & as "run in background" and cuts your address in half.
• Wrong parameter name. The client sends query but your annotation says q. Spring answers 400, because the required parameter is missing.
• No paging limit. A list endpoint with no size limit can return thousands of rows. Always cap the number of results.
• Using it for secrets. Query strings show up in logs and browser history. Never send passwords there.

Interview Questions

Frequently Asked Questions

What does @RequestParam do in Spring Boot?

It reads a value from the query string, such as category=phone, and passes it to a controller method parameter, converted to the type you declare.

Can I skip @RequestParam and just name the parameter?

For simple types such as String or int, Spring still binds a parameter by name. The annotation makes the intent clear and lets you set required and defaultValue.

How do I read every parameter at once?

Declare @RequestParam Map<String, String> all. It holds every name and value from the request.

Can @RequestParam be used with POST?

Yes. It reads query parameters in any request, and it also reads the fields of a normal HTML form. For JSON bodies use @RequestBody.

Related Topics

• @PathVariable: identify one item from the address path.
• @RequestBody: read a JSON body into a Java object.
• @RequestMapping: map addresses and conditions to methods.
• HTTP Status Codes in Spring Boot: understand the 400 replies you saw here.