Introduction

@RequestParam and @PathVariable both bind incoming request data in Spring, but they communicate different meanings in an API. A path variable usually identifies the resource being addressed, while a request parameter usually modifies or filters the request without redefining the resource path itself.

Use @PathVariable for Resource Identity

A path variable comes from the URL path template.

1@GetMapping("/users/{id}")
2public String getUser(@PathVariable Long id) {
3    return "User " + id;
4}

Here the id is part of the route itself. Without that segment, the request points to a different endpoint altogether.

This is why @PathVariable is a natural fit for resource identifiers, nested resources, or URLs that model hierarchy.

Use @RequestParam for Query Options

A request parameter comes from the query string.

1@GetMapping("/users")
2public String listUsers(@RequestParam(defaultValue = "0") int page,
3                        @RequestParam(defaultValue = "20") int size) {
4    return "page=" + page + ", size=" + size;
5}

These values shape how the request behaves, but they do not change the core resource path.

That makes @RequestParam a good fit for paging, sorting, filtering, or optional flags.

Semantic Difference Matters

Consider these two URLs:

• '/users/42'
• '/users?page=2'

They are not expressing the same kind of information. The first one targets a specific user resource. The second one still targets the users collection, but asks for a different view of it.

That semantic distinction is the real reason the two annotations exist.

Optionality and Defaults

@RequestParam supports defaults and optional values more naturally.

1@GetMapping("/search")
2public String search(@RequestParam(required = false) String q,
3                     @RequestParam(defaultValue = "relevance") String sort) {
4    return "q=" + q + ", sort=" + sort;
5}

@PathVariable is usually required because the path template itself expects it. If the path segment is missing, the request generally matches a different route or no route at all.

Good REST Design Heuristic

A simple rule works well most of the time:

• if the value identifies “which resource,” use @PathVariable
• if the value modifies “how to fetch or present it,” use @RequestParam

This keeps your URLs more predictable and makes the controller signature reflect the real meaning of the request.

That distinction also helps clients. Well-structured URLs make it obvious which values are mandatory parts of the route and which ones are optional request controls, which improves API readability before anyone even opens the controller code.

It also helps server-side maintenance, because route intent stays consistent across controllers instead of drifting into ad hoc URL styles that mix identifiers and filters unpredictably.

That consistency becomes more valuable as an API grows and more endpoints need to feel coherent.

Common Pitfalls

• Using query parameters for core resource identity when the path should express that identity directly.
• Stuffing every possible value into the path even when some values are really optional filters.
• Forgetting that @RequestParam can be optional or have a default, which is often exactly what pagination and filtering need.
• Treating the two annotations as interchangeable because they both “read values from the request.”
• Designing URLs around framework mechanics instead of resource semantics.

Summary

• '@PathVariable is usually for resource identity embedded in the URL path.'
• '@RequestParam is usually for query options such as filtering, sorting, or pagination.'
• The difference is semantic, not just syntactic.
• '@RequestParam supports optional values and defaults more naturally.'
• Good Spring APIs become easier to read when path and query data each express the right kind of meaning.