Spring @PathVariable vs @RequestParam: URL and Query Parameter Binding

Every Spring developer has written a controller that takes parameters from the URL. But I've seen more production outages from misusing @PathVariable and @RequestParam than from any other annotation. It sounds simple, but the devil's in the details.

In this article, I'll share hard-won lessons from debugging a fintech startup's API that crashed under load because someone used @PathVariable for an optional filter. You'll learn exactly when to use each annotation, how to handle edge cases, and what the official docs gloss over.

We'll cover basic binding, advanced configuration, validation, and production debugging. By the end, you'll never confuse these two again – and your APIs will be more robust for it.

Understanding @PathVariable: Binding URL Template Variables

The @PathVariable annotation binds a method parameter to a URI template variable. It's the go-to for extracting values from the URL path itself. For example, in a REST API for a payment system, you might have:

@GetMapping("/payments/{paymentId}") public Payment getPayment(@PathVariable Long paymentId) { ... }

This is straightforward, but I've seen teams misuse it for optional parameters. Remember: path variables are always required by nature – they're part of the path. If you make them optional, you're breaking REST conventions.

Spring automatically converts the string value to the target type (e.g., Long, Integer, UUID). If conversion fails, you get a TypeMismatchException. Always use wrapper types (Long, Integer) instead of primitives to allow null in case of missing values – though missing path variables are rare, they can happen with misconfigured routes.

You can also use multiple path variables:

@GetMapping("/users/{userId}/payments/{paymentId}") public Payment getPayment(@PathVariable Long userId, @PathVariable Long paymentId) { ... }

Pro tip: If you're using Spring Boot 2.2+, the annotation value is inferred from the method parameter name if compiled with -parameters. Otherwise, you must specify the name explicitly: @PathVariable("paymentId").

@RestController
@RequestMapping("/api/payments")
public class PaymentController {

    @GetMapping("/{paymentId}")
    public Payment getPayment(@PathVariable Long paymentId) {
        // Always use wrapper type to avoid NPE
        return paymentService.findById(paymentId);
    }

    @GetMapping("/{paymentId}/receipt")
    public Receipt getReceipt(@PathVariable("paymentId") Long paymentId) {
        return paymentService.getReceipt(paymentId);
    }
}

Mastering @RequestParam: Query Parameters and Form Data

The @RequestParam annotation extracts values from query parameters (after ?) or form data. It's perfect for optional filters, pagination, and sorting. For example:

@GetMapping("/payments") public List<Payment> listPayments(@RequestParam(required = false, defaultValue = "0") int page, @RequestParam(required = false, defaultValue = "10") int size) { return paymentService.findAll(page, size); }

Key differences from @PathVariable: @RequestParam can be optional, has a default value, and supports multiple values (e.g., ?status=PENDING&status=COMPLETED). Use @RequestParam List<String> status to capture repeated parameters.

One common mistake: forgetting that @RequestParam is required by default. If a client omits the parameter, Spring throws MissingServletRequestParameterException. Always set required=false and provide a sensible default unless the parameter is truly mandatory.

Another gotcha: type conversion. If you expect an enum, Spring does automatic conversion if the enum has a String constructor or @JsonCreator. But for custom types, you'll need a Converter or PropertyEditor.

For form data, @RequestParam works the same way – it binds to form fields in POST requests. But for complex objects, use @ModelAttribute instead.

@RestController
@RequestMapping("/api/payments")
public class PaymentSearchController {

    @GetMapping
    public List<Payment> searchPayments(
            @RequestParam(required = false, defaultValue = "0") int page,
            @RequestParam(required = false, defaultValue = "20") int size,
            @RequestParam(required = false) String status,
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate fromDate) {
        return paymentService.search(page, size, status, fromDate);
    }
}

When to Use Which: A Decision Framework

Here's the hard truth: most teams get this wrong. They use @PathVariable for everything because it looks cleaner, or they use @RequestParam for everything because it's more flexible. Both are bad.

Use this decision framework:

1. Is the parameter a unique identifier for a resource? Use @PathVariable.
2. Example: /users/{userId} – userId uniquely identifies a user.
3. Is the parameter optional, or does it filter/modify the response? Use @RequestParam.
4. Example: /users?role=admin – role filters the list.
5. Is the parameter part of the resource hierarchy? Use @PathVariable.
6. Example: /users/{userId}/orders/{orderId} – orderId is nested under userId.
7. Is the parameter a configuration or metadata? Use @RequestParam.
8. Example: /users?includeAddress=true – includeAddress modifies the response shape.
9. Is the parameter required for the request to make sense? If it's in the path, use @PathVariable. If it's in the query, use @RequestParam (required=true).

I once worked on a SaaS billing system where the team used @PathVariable for an optional 'include_discount' flag. The result? A bunch of URL patterns like /invoices/{id}/{includeDiscount} that were ugly and confusing. We refactored to use @RequestParam and the API became much cleaner.

// Good: @PathVariable for resource identifier
@GetMapping("/users/{userId}")
public User getUser(@PathVariable Long userId) { ... }

// Good: @RequestParam for optional filter
@GetMapping("/users")
public List<User> getUsers(@RequestParam(required = false) String role) { ... }

// Bad: @PathVariable for optional flag
@GetMapping("/users/{userId}/{includeAddress}") // Don't do this!
public User getUser(@PathVariable Long userId, @PathVariable boolean includeAddress) { ... }

// Good: @RequestParam for optional flag
@GetMapping("/users/{userId}")
public User getUser(@PathVariable Long userId, @RequestParam(required = false, defaultValue = "false") boolean includeAddress) { ... }

Advanced Binding: Custom Converters and Validation

Spring's default type conversion works for primitives, strings, dates, and enums. But what if you have a custom type like a PaymentId value object? You need a Converter.

Create a class implementing org.springframework.core.convert.converter.Converter<String, PaymentId>:

public class PaymentIdConverter implements Converter<String, PaymentId> { @Override public PaymentId convert(String source) { return new PaymentId(source); // validate and parse } }

Then register it in a WebMvcConfigurer:

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addFormatters(FormatterRegistry registry) { registry.addConverter(new PaymentIdConverter()); } }

Now you can use @PathVariable PaymentId paymentId directly.

Validation: Use Bean Validation (JSR-380) with @Validated on the controller class. For @RequestParam, add constraints like @Min, @Max, @Pattern on the method parameter:

@GetMapping("/payments") public List<Payment> listPayments( @RequestParam @Min(0) int page, @RequestParam @Max(100) @Min(1) int size) { ... }

This will throw ConstraintViolationException if validation fails. Handle it globally with @ExceptionHandler.

One gotcha: Spring's default error messages are ugly. Customize them with message attributes or a global exception handler that returns a consistent error JSON.

public class PaymentId {
    private final String value;
    public PaymentId(String value) {
        // Validate format, e.g., "PAY-12345"
        if (!value.matches("PAY-\\d+")) {
            throw new IllegalArgumentException("Invalid payment ID format");
        }
        this.value = value;
    }
    // getter, equals, hashCode
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new Converter<String, PaymentId>() {
            @Override
            public PaymentId convert(String source) {
                return new PaymentId(source);
            }
        });
    }
}

@RestController
public class PaymentController {
    @GetMapping("/payments/{paymentId}")
    public Payment getPayment(@PathVariable PaymentId paymentId) {
        return paymentService.findById(paymentId);
    }
}

What the Official Docs Won't Tell You

The Spring Framework reference documentation is excellent, but it glosses over several real-world gotchas that I've encountered in production.

1. Trailing Slash Ambiguity: A URL pattern like /users/{id}/ will match /users/123/ but also /users/ with an empty string for id. This can lead to subtle bugs. Always use regex patterns in @RequestMapping to enforce constraints: @GetMapping("/users/{id:[0-9]+}").
2. Encoding Issues: If your path variable contains a slash (e.g., a date like 2023/12/01), Spring will reject it because the slash is a path separator. Use @RequestParam for such values, or encode the slash as %2F and configure Tomcat to allow encoded slashes: server.tomcat.internal-proxies=.* and set relaxedQueryChars.
3. Optional @PathVariable with Map: You can use @PathVariable Map<String, String> to capture all path variables, but it's rarely needed. However, if you have optional path variables, this is the only way to handle them – and the docs don't emphasize that path variables are always required in the pattern.
4. @RequestParam with Default Values and Type Conversion: If you set defaultValue="0" for an int parameter, but the client sends an empty string (?page=), Spring will use the default value. However, if you set defaultValue="" for a String, it becomes empty string, not null. This matters for validation.
5. Performance Impact: In high-throughput systems, binding many @RequestParam parameters (e.g., 20+ filters) can be slow because Spring uses reflection to set each parameter. Consider using a single @ModelAttribute or a custom argument resolver for complex filters.

I learned these the hard way while debugging a payment gateway that failed under load because of path variable encoding issues. The client was sending dates with slashes, and we had to scramble to fix it.

// Prevent empty path variable from trailing slash
@GetMapping("/users/{id:[0-9]+}")
public User getUser(@PathVariable Long id) {
    return userService.findById(id);
}

// Or use a regex that rejects empty
@GetMapping("/users/{id:\\d+}")
public User getUser(@PathVariable Long id) { ... }

Testing Parameter Binding: Integration Tests That Catch Issues

You should never trust that your parameter binding works without tests. Integration tests using MockMvc or WebTestClient are essential. Here's how to test both annotations:

For @PathVariable, test with valid and invalid path values:

mockMvc.perform(get("/api/users/123")) .andExpect(status().isOk());

mockMvc.perform(get("/api/users/abc")) // invalid type .andExpect(status().isBadRequest());

For @RequestParam, test with missing, empty, and multiple values:

mockMvc.perform(get("/api/payments")) .andExpect(status().isOk()); // should work with defaults

mockMvc.perform(get("/api/payments?page=1&size=abc")) .andExpect(status().isBadRequest()); // invalid size

Also test optional parameters: ensure that omitting them uses the default value.

One thing the docs don't stress: test your custom converters. If you have a PaymentId converter, test that it correctly parses valid strings and throws appropriate exceptions for invalid ones.

Use @WebMvcTest to load only the web layer, and mock the service layer. This keeps tests fast and focused.

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void testGetUserWithValidId() throws Exception {
        mockMvc.perform(get("/api/users/123"))
               .andExpect(status().isOk());
    }

    @Test
    void testGetUserWithInvalidId() throws Exception {
        mockMvc.perform(get("/api/users/abc"))
               .andExpect(status().isBadRequest());
    }

    @Test
    void testListUsersWithDefaults() throws Exception {
        mockMvc.perform(get("/api/users"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.page").value(0));
    }

    @Test
    void testListUsersWithCustomParams() throws Exception {
        mockMvc.perform(get("/api/users?page=1&size=50"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.page").value(1));
    }
}