Handling Incoming Request Data with @PathVariable and @RequestParam

@PathVariable: Extracting Data from the URL Path

The @PathVariable annotation is used to bind a method parameter to a URI template variable. In simpler terms, it lets you extract values from the URL's path itself. This is the standard way to identify a specific resource in a RESTful API.

Consider a URL for retrieving a specific user: GET /users/101. Here, 101 is the unique identifier for the user. To implement this, you define a placeholder in your mapping path with curly braces {} and use @PathVariable to capture its value.

Let's see this in action. The following article provides a clear, minimal example.

As you saw in the article, the implementation is straightforward:

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

    // A real implementation would query a database.
    @GetMapping("/{id}")
    public String getUserById(@PathVariable String id) {
        return "Fetching details for user with ID: " + id;
    }
}

Key points:

• The placeholder in the path is {id}.
• The @PathVariable annotation on the id parameter tells Spring to inject the value from that placeholder.
• If your method parameter name matches the placeholder name (like id here), you can use @PathVariable without any arguments. If they differ, you must specify the name: @PathVariable("id") String userId.

@RequestParam: Extracting Data from Query Parameters

The @RequestParam annotation is used to extract data from the query string portion of a URL (the part after the ?). These are typically used for filtering, sorting, or pagination.

For example, in a URL like GET /users?status=active&page=1, status and page are query parameters. You can use @RequestParam to bind their values to method parameters.

@RequestParam is very flexible. Let's look at an article that demonstrates how to define required and optional parameters, as well as provide default values.

Here is a consolidated example based on the article's concepts:

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

    @GetMapping
    public String findUsers(
            @RequestParam(value = "status", defaultValue = "all") String status,
            @RequestParam(value = "sort", required = false) String sort) {
        
        String response = "Searching for users with status: " + status;
        if (sort != null) {
            response += " | Sorting by: " + sort;
        }
        return response;
    }
}

Key points:

• A GET request to /users?status=active would set status to "active" and sort to null.
• A GET request to /users would use the default value, setting status to "all".
• The sort parameter is optional because required is set to false. If it's not provided, its value will be null.
• The status parameter is technically required by default, but since it has a defaultValue, it will never cause an error if omitted.

The following image provides a fantastic visual summary of how both annotations map parts of a URL to your method's parameters.

The Core Difference: When to Use Which?

You can technically pass an ID as a request parameter (e.g., /users?id=101), so how do you decide which to use? The choice is guided by RESTful API design principles. The "Code Decode" video below explains this distinction exceptionally well.

To summarize the video's excellent points:

• Use @PathVariable for mandatory identifiers. It's part of the resource's "address". A request to /users/{id} implies that the id is essential to locate the resource. Omitting it doesn't make sense; you'd be requesting a different endpoint (/users).
• Use @RequestParam for optional data or filters. They modify the representation of the resource or collection but don't change its fundamental identity. Sorting, filtering, and pagination are classic use cases. A request to /users is valid on its own; adding ?status=active simply refines the result.

A Detailed Comparison

Now that you understand the core design principle, let's compare some of the practical characteristics of these two annotations. This table provides a high-level summary.

Let's elaborate on a few of these points, as they have important practical implications.

1. Handling Multiple Values

@RequestParam makes it trivial to accept multiple values for the same parameter. You can map them directly to a List or an array. This is useful for endpoints where a user can select multiple tags, IDs, or categories.

• URL: GET /articles?tags=java,spring
• Code: @RequestParam List<String> tags

Doing this with @PathVariable is complex and generally not recommended, as it goes against the principle of identifying a single resource.

2. Ordering

The order of @PathVariables in the URL is critical because they are position-based.

• URL mapping: GET /organizations/{orgId}/users/{userId}
• Code: @PathVariable String orgId, @PathVariable String userId
  • Spring maps the first placeholder to the first parameter, the second to the second, and so on. Swapping orgId and userId in the URL would incorrectly assign the values.

The order of @RequestParams does not matter because they are identified by their key (name).

• ?status=active&sort=name is identical to ?sort=name&status=active.

3. URL Structure and Flexibility

Adding a new @RequestParam doesn't change the endpoint's URL mapping. It's a backward-compatible change. Clients who don't know about the new parameter can continue to call the endpoint as they did before.

Adding a new @PathVariable requires changing the URL mapping itself, which is a breaking change for existing clients.

• Changing from /users/{id} to /users/{id}/{profileType} requires all clients to update their request URLs.

For a deeper look at these practical differences, the same "Code Decode" video offers clear demonstrations.

Conclusion

In this lesson, you've learned how to make your REST endpoints significantly more capable by extracting dynamic data directly from a request's URL.

Key Takeaways:

• @PathVariable extracts values from URI path segments (e.g., {id} in /users/{id}). It is best used for mandatory identifiers that uniquely locate a resource.
• @RequestParam extracts values from query parameters (e.g., status in /users?status=active). It is ideal for optional filtering, sorting, or pagination criteria.
• @RequestParam supports attributes like required and defaultValue to provide greater flexibility.
• The choice between the two is a key API design decision: @PathVariable defines what the resource is, while @RequestParam defines how you want to view it.

In our next lesson, we will shift our focus back to the data payload of a request. We'll take a deeper dive into handling JSON, exploring @RequestBody in more detail and learning how to customize the structure of the JSON response sent back to the client.