@RestController and @RequestMapping in Spring Boot

Introduction

@RestController vs @Controller

Before mapping URLs, you need to understand what @RestController actually is.

@RestController is a composed annotation that combines @Controller and @ResponseBody. This means two things: the class is a Spring bean eligible for component scanning, and every method return value is written directly to the HTTP response body rather than being resolved through a view template.

// This
@RestController
public class UserController { }

// Is equivalent to this
@Controller
@ResponseBody
public class UserController { }

If you need to serve HTML pages (Thymeleaf, FreeMarker), use plain @Controller. If you are building a REST API where the response is JSON or XML, use @RestController. Mixing both in one class is possible by annotating specific methods with @ResponseBody, but it is cleaner to keep them separate.

@RequestMapping Basics

@RequestMapping on a class sets a base path. All methods in the class inherit it and append their own paths.

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

    @RequestMapping(method = RequestMethod.GET)
    public List<User> listUsers() {
        return userService.findAll();
    }

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

The URL resolves to /api/users for listUsers() and /api/users/{id} for getUser(), where {id} is a path variable.

HTTP Method Shortcuts

Writing method = RequestMethod.GET every time is tedious. Spring provides shortcut annotations for each HTTP method:

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

    @GetMapping             // equivalent to @RequestMapping(method = RequestMethod.GET)
    public List<User> listUsers() { ... }

    @GetMapping("/{id}")    // /api/users/{id} — GET
    public User getUser(@PathVariable Long id) { ... }

    @PostMapping           // /api/users — POST
    public User createUser(@RequestBody @Valid UserInput input) { ... }

    @PutMapping("/{id}")   // /api/users/{id} — PUT
    public User updateUser(@PathVariable Long id, @RequestBody @Valid UserInput input) { ... }

    @DeleteMapping("/{id}") // /api/users/{id} — DELETE
    public void deleteUser(@PathVariable Long id) { ... }

    @PatchMapping("/{id}")  // /api/users/{id} — PATCH
    public User patchUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) { ... }
}

All six shortcut annotations (@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping, @OptionsMapping) accept the same parameters as @RequestMapping: value, path, method, params, headers, consumes, produces.

Path Variables

Use @PathVariable to extract dynamic segments from the URL path.

@GetMapping("/users/{id}/orders/{orderId}")
public Order getUserOrder(
        @PathVariable Long id,
        @PathVariable Long orderId) {
    return orderService.findForUser(id, orderId);
}

Spring matches {id} and {orderId} to the method parameters by name. You can also specify the variable name explicitly if your parameter name has been erased by the Java compiler (due to -parameters flag not being set):

@PathVariable("id") Long userId  // explicit name when compiler strips parameter names

Multiple path variables in a single URL are fine—each maps to its own parameter. Just make sure the parameter types are compatible with what appears in the URL. If a user sends /users/abc/orders/123, Spring throws a type mismatch exception and returns a 400 Bad Request.

Regex Constraints on Path Variables

You can constrain what a path variable matches using regex syntax:

@GetMapping("/users/{id:^[0-9]{1,10}$}")
public User getUserByNumericId(@PathVariable Long id) { ... }

This endpoint only matches when id is a numeric string of 1 to 10 digits. Anything else returns 404. This is useful when you have multiple endpoints with overlapping patterns and need to disambiguate.

Query Parameters

Use @RequestParam for URL query strings and form data.

@GetMapping("/users/search")
public List<User> searchUsers(
        @RequestParam String name,
        @RequestParam(required = false) String email,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {
    return userService.search(name, email, page, size);
}

Called with: /api/users/search?name=alice&email=alice@example.com&page=2&size=10

Key points about @RequestParam:

• required = false makes the parameter optional—method must handle null
• defaultValue = “0” provides a value when the parameter is absent
• You cannot combine required = false with a primitive (int, boolean) because primitives cannot be null—use their wrapper types (Integer, Boolean) instead
• The parameter name in the method must match the query string key, or use @RequestParam(“name”) to map explicitly

Request Body

Use @RequestBody to deserialize the request body into a Java object. Spring uses the Content-Type header to select the appropriate HttpMessageConverter.

@PostMapping("/users")
public User createUser(@RequestBody @Valid UserInput input) {
    return userService.create(input);
}

@Valid (from Bean Validation, JSR-380) triggers validation on the input object before the method runs. If validation fails, Spring throws a MethodArgumentNotValidException and returns a 422 Unprocessable Entity with details.

For JSON, Spring uses MappingJackson2HttpMessageConverter by default. For XML, you need jaxb2-root-http-message-converter on the classpath. For plain text, StringHttpMessageConverter handles it.

Response Handling

@RestController methods can return:

Plain objects — serialized via HttpMessageConverter:

@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.findById(id);  // serialized to JSON automatically
}

ResponseEntity<T> — full control over status code, headers, and body:

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody @Valid UserInput input) {
    User created = userService.create(input);
    return ResponseEntity.created(URI.create("/api/users/" + created.getId()))
            .body(created);
}

void — suitable for responses where the status is set via ServletResponse or when you handle the response directly:

@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {
    userService.delete(id);
    // Returns 200 OK with empty body
}

Content Negotiation

Spring MVC uses the Accept header to determine the response format. If a client sends Accept: application/json, it gets JSON. If it sends Accept: application/xml, it gets XML (if an XML converter is configured).

You can also force a format via the produces attribute on the mapping:

@GetMapping(value = "/users/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
public User getUserAsJson(@PathVariable Long id) { ... }

@GetMapping(value = "/users/{id}", produces = MediaType.APPLICATION_XML_VALUE)
public User getUserAsXml(@PathVariable Long id) { ... }

This creates two distinct endpoints differentiated by the Accept header. Spring matches based on the Accept header, not the URL.

Similarly, consumes restricts what request content types are accepted:

@PostMapping(value = "/users", consumes = MediaType.APPLICATION_JSON_VALUE)
public User createUser(@RequestBody @Valid UserInput input) { ... }

A request with Content-Type: text/plain to this endpoint returns 415 Unsupported Media Type.

Request Flow

graph TD
    A[HTTP Request] --> B[DispatcherServlet]
    B --> C[HandlerMapping<br/>matches URL + HTTP method]
    C --> D[HandlerAdapter<br/>calls controller method]
    D --> E[Method executes<br/>@PathVariable, @RequestParam, @RequestBody resolved]
    E --> F[Return value processed<br/>via HttpMessageConverter]
    F --> G[HTTP Response sent]

DispatcherServlet is the front controller that routes all requests. HandlerMapping implementations (usually RequestMappingHandlerMapping) scan for @RequestMapping annotations and build a map of URL patterns to handler methods. HandlerAdapter (usually RequestMappingHandlerAdapter) invokes the actual method, resolving parameters along the way.

When to Use @RestController vs @ControllerAdvice

@ControllerAdvice (or @RestControllerAdvice which combines both) lets you apply cross-cutting behavior to all controllers—like global exception handling, binding result normalization, or adding common response headers.

Use @RestControllerAdvice when all your responses are bodies (REST APIs). Use @ControllerAdvice when you have template-based controllers mixed in.

Failure Scenarios

405 Method Not Allowed

• Cause: The URL exists but the HTTP method has no handler. For example, sending POST to /api/users/123 when only @GetMapping(“/{id}”) is defined.
• Fix: Add the missing mapping method or use @RequestMapping(method = RequestMethod.ALL) to catch all methods on a given path.

404 Not Found

• Cause: No handler matches the URL pattern. Check for typos, missing leading slashes, or mismatched path variable names.
• Fix: Verify the @GetMapping(“/users/{id}”) annotation matches the URL being requested.

400 Bad Request from path variable type mismatch

• Cause: Sending /users/abc when the parameter is declared as Long id. Spring cannot convert “abc” to a Long.
• Fix: Validate the input format on the client side, or use a regex constraint on the path variable.

415 Unsupported Media Type

• Cause: Sending a request with a Content-Type your endpoint does not consume. The @PostMapping defaults to consuming nothing unless you specify consumes.
• Fix: Add consumes = MediaType.APPLICATION_JSON_VALUE if your endpoint expects JSON.

Null @RequestParam when parameter is missing

• Cause: @RequestParam without required = false on an optional parameter, or using a primitive type.
• Fix: Use required = false with a wrapper type (Integer not int).

When to Use / When NOT to Use

When to Use @RestController

@RestController is the right choice when every method in your class returns data to be serialized directly into the HTTP response body — JSON, XML, plain text. If you are building a REST API, a microservice, or any endpoint-oriented service where views and templates are not involved, @RestController eliminates the boilerplate of annotating every method with @ResponseBody.

When NOT to Use @RestController

If you need to serve HTML pages through a template engine like Thymeleaf or FreeMarker, use plain @Controller. Mixing template rendering and REST endpoints in the same class is technically possible but creates confusion. If you find yourself adding @ResponseBody to most methods in a @Controller class, just switch to @RestController instead.

When to Use @GetMapping / @PostMapping etc

Use the specific HTTP method annotations whenever the method only handles one HTTP verb. They reduce noise in your code and make the intent of each endpoint immediately obvious when reading the class. These annotations also set up the correct consumes and produces defaults automatically.

When to Use @RequestMapping with Explicit Method

Use @RequestMapping(method = RequestMethod.GET) (or the equivalent) when you need to handle multiple HTTP methods on the same path, or when you are building a less common endpoint (like OPTIONS or TRACE) that does not have its own shortcut annotation.

When to Use Path Variables

Use @PathVariable when a piece of data is inherently part of the URL structure — a resource ID, a username, an order number. The URL /users/42 makes sense as a bookmarkable, shareable resource address. Do not cram everything into path variables though; if the parameter is an optional filter rather than a resource identifier, @RequestParam is more appropriate.

When to Use @RequestParam

Use @RequestParam for query parameters that represent optional filters, sorting, pagination, or any data that is not intrinsic to the resource identity. If you find yourself building queries like /search?name=alice&status=active, those are query parameters.

Trade-Off Table

Annotation	Best Used For	Avoid When
@RestController	REST APIs returning JSON/XML	Template-based HTML rendering
@Controller	View templates (Thymeleaf, JSP)	Pure API endpoints
@GetMapping	Read-only endpoint retrieval	Mutations (use POST/PUT/DELETE)
@PostMapping	Creating resources	Read operations (misleading semantics)
@PathVariable	Resource identifiers in URL path	Optional filters or search parameters
@RequestParam	Query parameters, optional filters	Core resource identity (use path var)
@RequestBody	JSON/XML payloads deserialized to object	Form fields (use @ModelAttribute)
ResponseEntity<T>	Full control over status, headers, body	Simple returns where 200 is assumed

Common Pitfalls / Anti-Patterns

1. Forgetting the leading slash on paths: @GetMapping(“users”) maps to /users relative to the servlet context, not /users relative to the class-level @RequestMapping. Be explicit: @GetMapping(“/users”).
2. Path variable name mismatch after compilation: If you compile without the -parameters flag, Java erases parameter names. Use @PathVariable(“id”) explicitly rather than relying on the compiler.
3. Combining @PathVariable and @RequestParam with the same name: They are independent; you can have /users/{id}?name=alice where both resolve to different values.
4. Returning null from a @GetMapping: This returns an empty JSON null or 204 No Content depending on your configuration. If null is a valid business response, return Optional<User> instead.
5. Missing @Valid on @RequestBody: Without it, invalid input passes through without validation errors. Always add @Valid for user input.

Security Notes

• Validate all path variables and request parameters: They are user-controlled. A Long id path variable that queries a database should check ownership before returning data.
• Limit request body size: Prevent large payload attacks by setting server.tomcat.max-http-form-post-size or equivalent for your server.
• Sensitive data in query strings: Query parameters appear in logs and browser history. Do not pass tokens, passwords, or PII as query parameters—use headers or request bodies instead.
• CORS configuration: If your API is called from browsers, configure CORS via @CrossOrigin on the controller or a global WebMvcConfigurer—do not allow arbitrary origins in production.

Observability Checklist

• Verify all endpoints are reachable via a contracts test or API integration test
• Confirm 405 is returned when an HTTP method is not allowed on a valid URL
• Check that path variable regex constraints are tested
• Confirm @Valid on @RequestBody methods catches invalid input and returns 422
• Verify CORS is configured correctly for all origins that need access
• Log request paths at INFO or DEBUG level to track which endpoints are hit
• Confirm sensitive data is not logged in query strings

Quick Recap Checklist

• @RestController = @Controller + @ResponseBody (all return values go to response body)
• @RequestMapping on a class sets the base path; methods append to it
• Use @GetMapping / @PostMapping / @PutMapping / @DeleteMapping / @PatchMapping as shortcuts for common verbs
• @PathVariable extracts dynamic URL segments; use explicit names if compiling without -parameters
• @RequestParam extracts query string parameters; use required = false for optional ones
• @RequestBody deserializes the request body; add @Valid to trigger Bean Validation
• ResponseEntity<T> gives full control over status, headers, and body
• Use produces and consumes to restrict media types for content negotiation
• @ControllerAdvice / @RestControllerAdvice for global exception handling across all controllers
• Never pass sensitive data in query string parameters

Interview Questions

Further Reading

• Spring Boot Reference Documentation — Building REST APIs — Official docs on Spring MVC and REST support
• Spring Framework Documentation — Web on Servlet Stack — Deep dive into DispatcherServlet, HandlerMapping, and HandlerAdapter
• Bean Validation (JSR-380) — Specification behind @Valid and constraint annotations
• HTTP Status Codes — Mozilla MDN — Reference for 400, 404, 405, 415, 422 semantics
• Spring MVC Content Negotiation — Covers produces/consumes, content type resolution, and ContentNegotiationConfigurer

Conclusion

@RestController and @RequestMapping form the foundation of Spring Boot’s web layer. Every endpoint in a Spring Boot REST API traces back to these two annotations—one marking the class as a web handler, the other binding URL patterns and HTTP methods to handler methods. The convenience variants (@GetMapping, @PostMapping, and their counterparts) reduce boilerplate and make the intended HTTP verb immediately visible when reading code.

The annotations that power parameter binding—@PathVariable, @RequestParam, and @RequestBody—each solve distinct binding problems: URL segments, query parameters, and request bodies respectively. Mixing these up is the most common source of 400 and 405 errors in Spring MVC applications. @PathVariable is for resource identifiers baked into the URL path. @RequestParam is for optional modifiers like pagination and search filters. @RequestBody is for structured payloads deserialized from the request body. Always pair @RequestBody with @Valid to enforce constraint validation before your method executes.

For response construction, prefer plain return values for simple read endpoints where 200 is always correct. Reach for ResponseEntity<T> when you need to set status codes, add headers, or return different status codes based on business logic. Centralize error and validation handling in a @RestControllerAdvice rather than scattering try-catch blocks across controllers. Content negotiation through the Accept header and produces/consumes attributes lets a single URL serve multiple representations (JSON, XML) to different clients, but only when the converters for those formats are on the classpath.