Building REST APIs
@PathVariable, @RequestParam, @RequestBody — Handling Request Data
Parsing JSON payloads, query paths, and URL parameters.
Introduction
When designing APIs, you must capture input data sent by the client. Spring Boot provides three primary annotations to extract request data: @PathVariable, @RequestParam, and @RequestBody. Each serves a distinct routing or structural purpose, and selecting the correct annotation is key to maintaining proper RESTful API semantics.
Why It Matters
Choosing how to bind inputs dictates how clean and navigable your endpoints are. Path parameters are used to locate specific resources, request params are used to query and filter collections, and request bodies are used to submit structured payloads. Getting these mixed up leads to unmaintainable, confusing API specifications.
Real-World Analogy
Think of navigating a large library:
- @PathVariable: The exact bookshelf location or call number. It points to a specific item:
/aisles/4/shelves/2/book/123. You cannot browse without this unique pointer. - @RequestParam: Filters or search parameters. You look for books:
/books?genre=history&author=smith. The books exist independently, and you are filtering the set. - @RequestBody: The application form you fill out to request a library membership card, containing multi-field information packed into a single document envelope.
How It Works
Spring's controller parameter resolution is handled by implementations of the HandlerMethodArgumentResolver interface:
| Annotation | Resolver Under the Hood | HTTP Segment |
|---|---|---|
| @PathVariable | PathVariableMethodArgumentResolver | URL path parameters (e.g., /api/users/{id}) |
| @RequestParam | RequestParamMethodArgumentResolver | Query params (e.g., ?page=2) or form parameters |
| @RequestBody | RequestResponseBodyMethodProcessor | HTTP payload body (JSON, XML, etc.) |
Practical Example
Here is an endpoint demonstrating how to capture inputs using all three annotations:
Quick Quiz
Q1: What is the default behavior in Spring Boot if a @RequestParam is missing from the request URL?
A) It is bound as null automatically without exceptions
B) It throws a MissingServletRequestParameterException (results in HTTP 400 Bad Request)
C) The application throws an Internal Server Error (HTTP 500)
D) The server automatically redirects the client
Answer: B — By default, @RequestParam makes parameters mandatory. To change this, set required = false, or specify a defaultValue.
Q2: When should you use @PathVariable instead of @RequestParam?
A) When sending binary files
B) When the value is sensitive and needs encryption
C) When identifying a specific resource instance within a hierarchical path
D) When mapping dynamic search criteria with filters
Answer: C — Path variables identify resources (e.g. /users/123), whereas request parameters are for filtering, sorting, or pagination details (e.g. ?role=ADMIN).
Scenario-Based Challenge
Production Scenario:
You are building a search API that filters orders by multiple optional criteria: orderDate, status, minAmount, maxAmount, and customerId. Writing a method signature with five optional @RequestParam annotations looks cluttered. How can you clean this up using Spring MVC capabilities?
Spring can automatically map incoming query parameters to a plain Java object (DTO) without any annotation on the object parameter. You can define a OrderSearchCriteria class containing properties matching the query parameter names, and simplify the controller method signature to:
public List<OrderDto> searchOrders(OrderSearchCriteria criteria) { ... }
Spring resolves this via query parameter binding, keeping the signature neat and extensible.
Interview Questions
1. What is the difference between @RequestBody and ModelAttribute bindings?
@RequestBody reads the entire HTTP request body stream and converts it to a Java object using an HTTP message converter (ideal for JSON). @ModelAttribute reads parameters from the URL query string and form-encoded data, binding them directly to Java object fields using standard getter/setter properties.
2. Can you have multiple @RequestBody annotations in a single controller method signature?
No. The HTTP request body is sent as a single continuous input stream. Once read and deserialized by Spring, the stream is consumed. You can only bind one parameter to @RequestBody per controller method.
Production Considerations
Avoid passing highly sensitive data (like passwords, credentials, or credit cards) through URL paths (@PathVariable) or query parameters (@RequestParam). Browsers, reverse proxies, and server access logs record request URLs in plain text, potentially exposing secrets. Always pass sensitive fields in the payload using @RequestBody over HTTPS.