Mastering Spring Boot: A Deep Dive into @PathVariable and @RequestParam Annotations

In Spring Boot, @PathVariable and @RequestParam are two of the most commonly used annotations for handling incoming HTTP requests. These annotations make it easy to capture data from the request URI and query parameters.

---

1. @PathVariable Annotation

The @PathVariable annotation is used to extract values from the URI template. It binds a method parameter to a URI variable.

When to Use @PathVariable?

• Use @PathVariable when you want to capture part of the URI as a method parameter.
• Ideal for RESTful web services, where specific resource identification is required.

Example:

Suppose you want to fetch a user’s details by their ID. The URL might look like this:

GET /users/{id}

Here’s how you can handle this in your Spring Boot controller:

@RestController
@RequestMapping("/users") 
public class UserController { 
@GetMapping("/{id}")
    public String getUserById(@PathVariable("id") Long userId) { 
return "User ID: " + userId; 
 }
}

Output:

For a request to /users/42, the response will be:

User ID: 42

Optional Path Variables:

You can make path variables optional by using java.util.Optional:

@GetMapping("/{id}")
public String getUserById(@PathVariable Optional<Long> id) {
    return id.map(userId -> "User ID: " + userId)
             .orElse("User ID not provided");
}

---

2. @RequestParam Annotation

The @RequestParam annotation is used to extract query parameters from the request URL.

When to Use @RequestParam?

• Use @RequestParam when you want to capture query parameters (e.g., filters, sorting criteria, etc.).
• It's useful for optional or additional parameters.

Example:

Suppose you want to filter users by their name and age. The URL might look like this:

GET /users?name=John&age=25

Here’s how to handle it:

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

    @GetMapping
    public String getUsers(@RequestParam String name, @RequestParam int age) {
        return "Name: " + name + ", Age: " + age;
    }
}

Output:

For a request to /users?name=John&age=25, the response will be:

Name: John, Age: 25

Optional Query Parameters:

You can specify default values for query parameters:

@GetMapping
public String getUsers(
        @RequestParam(defaultValue = "Unknown") String name,
        @RequestParam(defaultValue = "0") int age) {
    return "Name: " + name + ", Age: " + age;
}

Now, if the query parameters are missing, default values will be used.

---

3. Key Differences Between @PathVariable and @RequestParam

Aspect	@PathVariable	@RequestParam
Source of Data	URI path	Query string
Use Case	For identifying resources	For filtering or additional options
Required by Default	Yes	No (can provide default values)
Example URL	/users/{id} (e.g., /users/42)	/users?name=John&age=25

---

4. Using Both @PathVariable and @RequestParam

You can use @PathVariable and @RequestParam together in a single endpoint to handle more complex scenarios.

Example:

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

    @GetMapping("/{category}")
    public String getProducts(
            @PathVariable String category,
            @RequestParam(defaultValue = "0") int minPrice,
            @RequestParam(defaultValue = "1000") int maxPrice) {
        return "Category: " + category + ", Price Range: " + minPrice + "-" + maxPrice;
    }
}

URL:

GET /products/electronics?minPrice=100&maxPrice=500

Response:

Category: electronics, Price Range: 100-500

---

5. Best Practices

1. Use Descriptive Path and Query Parameters:

   • Ensure URI paths and query parameters are meaningful for better API usability.

2. Validation:

   • Validate parameters using Spring's validation annotations like @Valid or by implementing custom validators.

3. Optional Parameters:

   • Make optional parameters explicit by setting default values or using Optional.

4. Consistent Design:

   • Follow RESTful principles where @PathVariable is used for resource identification, and @RequestParam is used for filtering and sorting.

---

Conclusion

Understanding and effectively using @PathVariable and @RequestParam can significantly enhance your Spring Boot applications, making them more intuitive and easier to work with. By following best practices, you can build robust APIs that adhere to RESTful principles and cater to various client needs.