@PathVariable Annotation in Spring Boot

📘 Premium Read: Access my best content on Medium member-only articles — deep dives into Java, Spring Boot, Microservices, backend architecture, interview preparation, career advice, and industry-standard best practices.

✅ Some premium posts are free to read — no account needed. Follow me on Medium to stay updated and support my writing.

🎓 Top 10 Udemy Courses (Huge Discount): Explore My Udemy Courses — Learn through real-time, project-based development.

▶️ Subscribe to My YouTube Channel (172K+ subscribers): Java Guides on YouTube

🚀 Introduction: What is @PathVariable in Spring Boot?

In Spring Boot, the @PathVariable annotation is used to extract values from the URL path and bind them to method parameters. It is commonly used in REST APIs to retrieve resources based on dynamic path values, such as user IDs, product names, or order numbers.

✅ Key Features of @PathVariable:
✔ Extracts dynamic path values from the URL.
✔ Supports multiple path variables in a single request.
✔ Works with different data types (int, String, UUID).
✔ Supports optional path variables with default values.

📌 In this guide, you’ll learn:
✅ How to use @PathVariable to extract path parameters.
✅ How it differs from @RequestParam.
✅ Best practices for handling optional path variables.

1️⃣ Basic Example: Extracting a Single Path Variable

📌 Example: Retrieving a User by ID from the URL Path

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

    @GetMapping("/{id}")
    public String getUserById(@PathVariable int id) {
        return "User with ID: " + id;
    }
}

📌 GET Request (GET /api/users/5)
📌 Response:

User with ID: 5

✅ Spring automatically converts the id value from the URL into an int.

2️⃣ Using @PathVariable with Different Data Types

You can use UUID, String, or other data types as path variables.

📌 Example: Retrieving a Product by UUID

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

    @GetMapping("/{productId}")
    public String getProductById(@PathVariable UUID productId) {
        return "Product ID: " + productId;
    }
}

📌 GET Request (GET /api/products/550e8400-e29b-41d4-a716-446655440000)
📌 Response:

Product ID: 550e8400-e29b-41d4-a716-446655440000

✅ Spring automatically converts the UUID string into a UUID object.

3️⃣ Using Multiple @PathVariable Parameters

You can extract multiple values from the URL.

📌 Example: Retrieving an Order by User ID and Order ID

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @GetMapping("/{userId}/order/{orderId}")
    public String getOrderById(@PathVariable int userId, @PathVariable int orderId) {
        return "User ID: " + userId + ", Order ID: " + orderId;
    }
}

📌 GET Request (GET /api/orders/101/order/5001)
📌 Response:

User ID: 101, Order ID: 5001

✅ Allows fetching specific resources using multiple parameters.

4️⃣ Using @PathVariable with Custom Names

By default, the method parameter name must match the path variable name. If they are different, use @PathVariable("name").

📌 Example: Customizing Path Variable Names

@RestController
@RequestMapping("/api/books")
public class BookController {

    @GetMapping("/{isbn}")
    public String getBookByIsbn(@PathVariable("isbn") String bookIsbn) {
        return "Book ISBN: " + bookIsbn;
    }
}

📌 GET Request (GET /api/books/978-3-16-148410-0)
📌 Response:

Book ISBN: 978-3-16-148410-0

✅ Useful when method parameter names differ from path variable names.

5️⃣ Handling Optional @PathVariable Values

By default, @PathVariable is required. You can make it optional by using required = false and a default value.

📌 Example: Handling Optional Path Variables

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

    @GetMapping({"/{id}", "/"})
    public String getEmployee(@PathVariable(required = false) Integer id) {
        if (id == null) {
            return "Fetching all employees...";
        }
        return "Fetching employee with ID: " + id;
    }
}

📌 GET Request (GET /api/employees)
📌 Response:

Fetching all employees...

📌 GET Request (GET /api/employees/10)
📌 Response:

Fetching employee with ID: 10

✅ Allows retrieving all employees when no ID is provided.

6️⃣ @PathVariable vs @RequestParam

Feature	@PathVariable	@RequestParam
Use Case	Extract values from the URL path	Extract values from query parameters
Required?	Required by default (can be optional)	Optional by default (can be required)
Format	GET /api/users/5	GET /api/users?id=5
Best for	Unique resource identification	Filters, sorting, pagination

📌 Example: Using @RequestParam Instead of @PathVariable

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

    @GetMapping
    public String getUserById(@RequestParam int id) {
        return "User with ID: " + id;
    }
}

📌 GET Request (GET /api/users?id=5)
📌 Response:

User with ID: 5

✅ Use @PathVariable for resource identification and @RequestParam for filtering and sorting.

7️⃣ Handling Global Exceptions for @PathVariable

If a requested resource is not found, return a proper HTTP 404 Not Found response.

📌 Example: Handling ResourceNotFoundException

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<Map<String, String>> handleNotFound(ResourceNotFoundException ex) {
        Map<String, String> error = new HashMap<>();
        error.put("error", ex.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

📌 Throwing the Exception in Controller

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

    private final Map<Integer, String> products = Map.of(1, "Laptop", 2, "Phone");

    @GetMapping("/{id}")
    public String getProductById(@PathVariable int id) {
        if (!products.containsKey(id)) {
            throw new ResourceNotFoundException("Product not found with ID: " + id);
        }
        return products.get(id);
    }
}

📌 Response (GET /api/products/99 - Non-Existing Product):

{
  "error": "Product not found with ID: 99"
}

✅ Ensures proper error handling and meaningful responses.

🎯 Summary: Best Practices for Using @PathVariable

✅ Use @PathVariable for unique resource identification (e.g., /users/{id}).
✅ Use @RequestParam for optional query parameters (e.g., /users?id=5).
✅ Make path variables optional if needed (required = false).
✅ Use @ControllerAdvice for centralized exception handling.
✅ Use meaningful HTTP status codes (404 Not Found when a resource is missing).

🚀 Following these best practices ensures a clean, maintainable REST API in Spring Boot!