Query Parameters

Query parameters are used to send optional information to the server through the URL.

They help control how data is returned, without changing the actual resource.

Query parameters appear after the ? symbol and are written as key=value pairs.

What is a Query Parameter?

A query parameter is a key–value pair added to a URL to provide extra instructions to the server.

Example URL

/users?role=admin&page=1&size=10

Why Use Query Parameters?

Query parameters are used when you want to:

• Filter results
• Search data
• Sort records
• Implement pagination
• Pass optional values

They make APIs flexible, reusable, and user-friendly.

Query Parameters in Spring Boot

In Spring MVC / Spring Boot:

• Query parameters are accessed using @RequestParam
• They appear after ? in the URL
• Multiple parameters are separated using &

Basic Query Parameter Example

Query parameters are used to pass optional data to the server, typically for filtering or searching.

@GetMapping("/users")
public List<User>getUsers(@RequestParam String role) {
return userService.findByRole(role);
}

URL

/users?role=admin

Explanation

• @RequestParam extracts the value of role from the query string
• role=admin is used to filter users by role
• If role is missing, Spring throws an error unless marked optional

Multiple Query Parameters

You can pass multiple query parameters to filter, paginate, or sort data.

@GetMapping("/users")
public List<User>getUsers(
@RequestParam String role,
@RequestParamint page,
@RequestParamint size) {
return userService.findUsers(role, page, size);
}

URL

/users?role=admin&page=1&size=10

Explanation

• role → Filter users by role
• page → Specifies the page number for pagination
• size → Specifies the number of records per page
• Spring automatically binds query parameters to method arguments

Optional Query Parameters

Query parameters can be made optional using required = false. This allows the endpoint to work even if the parameter is not provided.

Controller Method

@GetMapping("/users")
public List<User> getUsers(
        @RequestParam(required = false) String role) {
    return userService.findUsers(role);
}

URL Examples

With query parameter:

/users?role=admin

Without query parameter:

/users

Explanation

• If role is provided, users are filtered by role.
• If role is not provided, all users are returned.
• Optional parameters are useful for flexible filtering and search endpoints.

Default Values in Query Parameters

You can provide default values for query parameters using defaultValue. If the client does not supply a value, Spring applies the default automatically.

Example

@GetMapping("/users")
public List<User>getUsers(
@RequestParam(defaultValue = "user") String role,
@RequestParam(defaultValue = "0")int page,
@RequestParam(defaultValue = "10")int size) {
return userService.findUsers(role, page, size);
}

• If role, page, or size are missing in the URL, the defaults "user", 0, and 10 are used.

URL Examples

All parameters provided:

/users?role=admin&page=1&size=5

Some parameters missing:

/users?page=2

→ role defaults to "user", size defaults to 10

Query Parameters for Pagination & Sorting

Query parameters are often used to paginate and sort data.

Example

@GetMapping("/products")
public List<Product>getProducts(
@RequestParamint page,
@RequestParamint size,
@RequestParam String sortBy) {
return productService.findProducts(page, size, sortBy);
}

URL Example

/products?page=0&size=10&sortBy=price

• Returns page 0 with 10 products per page, sorted by price.

Common Use Cases

• Filtering → ?status=active
• Searching → ?name=John
• Pagination → ?page=0&size=10
• Sorting → ?sort=name,asc

—> Used to customize API responses, not identify resources.

Key Characteristics of Query Parameters

• Optional – API works even if they are not provided
• Flexible – Easy to add or remove
• Order doesn’t matter – ?page=1&size=10 = ?size=10&page=1
• Supports default values – Server can apply defaults
• Used for customization – Filtering, sorting, pagination (not for identification)

Difference Between Query Parameters vs Path Parameters

When working with REST APIs in Spring Boot, it is very important to understand the difference between Path Parameters and Query Parameters.

Both are used in URLs, but their purpose is completely different.

Examples

/users/10            → Path parameter
/users?active=true  → Query parameter

Best Practices for Query Parameters

• Use query parameters for filters and options
• Do not use them to identify resources
• Keep names meaningful (page, size, sortBy)
• Combine logically with pagination and sorting
• Keep them optional whenever possible

Conclusion

Query parameters allow clients to customize API responses without changing the resource itself. They are ideal for filtering, searching, sorting, and pagination, making REST APIs more flexible, scalable, and easy to use. When designed correctly, query parameters improve both developer experience and API performance, while keeping URLs clean and REST-compliant.