Spring @PathVariable

🔍 What Is It?

@PathVariable binds a URI template variable to a method parameter.

Syntax:

• →Define a template variable: @GetMapping("/users/{id}")
• →Bind it: @PathVariable("id") Long id
• →Or with explicit name: @PathVariable("id") Long userId

Supported types:

• →String, int, long, Integer, Long
• →UUID, LocalDate
• →Other types supported by the configured conversion service; register a converter for a custom identifier when needed

Use an explicit annotation name even when it matches the Java parameter. Omitting it relies on retained parameter-name metadata, such as compilation with -parameters; parameter-name discovery changed in Spring Framework 6.1.

Request outcomes

Conversion is separate from existence and authorization. A valid ID or UUID does not prove the caller can access the resource. A negative Long also converts successfully; enforce domain constraints separately.

Multiple path variables:

@GetMapping("/users/{userId}/orders/{orderId}")
public OrderDto getOrder(
    @PathVariable("userId") Long userId,
    @PathVariable("orderId") Long orderId) { ... }

🎯 Why Do We Need It?

RESTful API design uses URL paths to identify resources directly. /users/42 is clearer and more semantic than /users?id=42 when the request is about one specific entity. @PathVariable makes resource identification explicit in the URL structure and keeps Spring Boot controller mappings aligned with REST conventions.

🏗️ What Happens in Real Projects?

Every CRUD API uses path variables for resource identification:

• →GET /api/v1/orders/{orderId} — get specific order
• →PUT /api/v1/users/{userId}/roles/{roleId} — assign role to user
• →DELETE /api/v1/products/{productId} — delete product
• →GET /api/v1/categories/{categorySlug}/products — products in category

⚙️ How It Works

Spring first matches the request path against the mapping, then resolves each URI variable by name and converts the captured text to the declared Java type. A conversion failure normally produces a 400 response before the controller body runs. Once conversion succeeds, the application still needs to perform domain validation, lookup, and access checks.

Optional path variables

required = false changes argument resolution; it does not make a missing URL segment match an existing pattern. Map both /users and /users/{id} if the same handler intentionally accepts both. Use a wrapper type or Optional for the missing value.

Dates and slash-containing paths

Use an explicit date format for a LocalDate argument. A normal {id} captures one path segment. Multi-segment capture such as {*path} depends on the configured PathPattern matching strategy and belongs at the end of a pattern; it is not an optional-segment syntax.

💻 Example

Path Variables in Practice — Single, multiple, and optional path variables.

import java.time.LocalDate;
import java.util.UUID;
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PathVariableDemoController {
    @GetMapping("/users/{id}")
    public String user(@PathVariable("id") Long userId) {
        return "User " + userId;
    }

    @GetMapping("/sessions/{id}")
    public String session(@PathVariable("id") UUID sessionId) {
        return sessionId.toString();
    }

    @GetMapping("/reports/{day}")
    public String report(@PathVariable("day")
            @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate day) {
        return day.toString();
    }

    @GetMapping({"/optional-users", "/optional-users/{id}"})
    public String optionalUser(@PathVariable(name = "id", required = false) Long id) {
        return id == null ? "All users" : "User " + id;
    }
}

// GET /users/42             -> User 42
// GET /users/abc            -> 400 with standard Spring MVC error handling
// GET /reports/2026-11-01   -> 2026-11-01
// GET /optional-users      -> All users
// GET /optional-users/42   -> User 42

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits