Path Parameters (Path Variables)

Path parameters (also called Path Variables) are values embedded directly inside the URL path.

They are used to identify a specific resource and form the backbone of RESTful API design.

If you are building APIs using Spring Boot or Spring MVC, understanding path parameters is essential.

What is a Path Parameter?

A path parameter is a dynamic value in the URL that represents a resource identifier, such as an ID.

Example URL

/users/10

Here, the server understands that the client is requesting user with ID = 10.

Why Use Path Parameters?

Path parameters are preferred in REST APIs because they:

• Clearly identify a specific resource
• Make URLs clean, readable, and meaningful
• Follow REST best practices
• Avoid exposing identifiers in query strings
• Support nested or hierarchical resources

Example:

/users/5/orders/1001

➡ Clearly represents Order 1001 belonging to User 5

Path Parameters in Spring Boot

In Spring MVC / Spring Boot:

• Path parameters are accessed using @PathVariable
• Defined using {} in the request mapping

Basic Path Variable Example

@GetMapping("/users/{id}")
public UsergetUser(@PathVariable Long id) {
return userService.findById(id);
}

Request

GET /users/10

Result

id =10

Spring automatically extracts 10 from the URL and assigns it to the id variable.

Multiple Path Parameters (Nested Resources)

Path variables are commonly used for hierarchical relationships.

@GetMapping("/users/{userId}/orders/{orderId}")
public OrdergetOrder(
@PathVariable Long userId,
@PathVariable Long orderId) {
return orderService.findOrder(userId, orderId);
}

URL

/users/5/orders/1001

• Clean
• REST-compliant
• Easy to understand

Path Variable Name Matching

In Spring, path variable names must match the method parameter name unless you explicitly specify the name inside @PathVariable.

Same Name (Recommended)

When the URL variable name and method parameter name are the same, you can use @PathVariable without any value.

@GetMapping("/products/{id}")
public ProductgetProduct(@PathVariable Long id) {
return productService.findById(id);
}

Different Variable Name

If the URL variable name and method parameter name are different, you must explicitly specify the variable name.

@GetMapping("/products/{productId}")
public ProductgetProduct(@PathVariable("productId") Long id) {
return productService.findById(id);
}

Optional Path Variables

Path variables are required by default.

To make them optional, you must define multiple URL mappings.

@GetMapping({"/users", "/users/{id}"})
public ObjectgetUsers(@PathVariable(required = false) Long id) {
return (id ==null)
            ? userService.findAll()
            : userService.findById(id);
}

⚠️ Use optional path variables carefully—they can reduce API clarity.

Path Variables with Regular Expressions

Spring allows regex validation directly in the URL.

@GetMapping("/users/{id:[0-9]+}")
public UsergetUser(@PathVariable Long id) {
return userService.findById(id);
}

• Accepts: /users/123
• Rejects: /users/abc

This improves API safety and validation.

Best Practices for Path Parameters

• Use path variables only for resource identification
• Use meaningful names (userId, orderId)
• Avoid optional path variables when possible
• Validate values using regex
• Never use path variables for filtering or sorting

Conclusion

• Path parameters are mandatory identifiers in REST APIs.
• Defined using {} and accessed with @PathVariable.
• Best suited for unique resource access.
• Improve API readability, clarity, and REST compliance.
• Essential for professional Spring Boot REST API design.