Spring

Spring REST controllers

A controller maps HTTP requests to Java methods.

🔎 Unravel this example Prerequisites (2)

Learn these first

Spring beans and dependency injection Jackson JSON

At a glance

Mental model

The controller is a switchboard operator: it looks at which line is ringing (method and URL), connects the call to the right desk (method), and passes along what the caller said (parameters and body).

What happens, in order

1@RestController marks a class whose methods return data directly@GetMapping("/orders/{id}") binds a method to GET requests for that path.
2Arguments are filled from the request: @PathVariable takes a piece of the URL, @RequestParam a query parameter, @RequestBody the body (parsed from JSON into an object by Jackson), and @RequestHeader a header
3The return value is converted to JSON and sent with status 200, unless you return ResponseEntity (full control of status and headers) or annotate with @ResponseStatus
4@ExceptionHandler or @RestControllerAdvice turns exceptions into proper error responses in one place instead of try/catch in every method

Remember

Keep controllers thin: validate input, call a service, shape the response
Add @Valid with bean validation annotations (@NotNull, @Size) on @RequestBody objects; failures produce a 400 automatically
A single DispatcherServlet receives every request, asks HandlerMapping which method matches, and delegates to HandlerAdapter, which resolves each argument with HandlerMethodArgumentResolvers and writes the result with HttpMessageConverters (Jackson for JSON)

Watch out

Business logic in the controllerReturning entities directlySkipping validation on request bodiesCatching exceptions everywhere instead of one advice class

Example (highlighted lines explain it)

@RestController@RequestMapping("/api/customers")public class CustomerController {    private final CustomerService service;    public CustomerController(CustomerService service) { this.service = service; }    @GetMapping("/{id}")    public CustomerDto get(@PathVariable long id) {        return service.find(id);    }}

line 1 uses RestController, the core of Spring REST controllers
line 2 uses RequestMapping, the core of Spring REST controllers
line 3 uses Controller, the core of Spring REST controllers
line 6 uses Controller, the core of Spring REST controllers
line 8 uses GetMapping, the core of Spring REST controllers
line 9 uses PathVariable, the core of Spring REST controllers

Read the full explanation (about 1 min)

A controller maps HTTP requests to Java methods. Spring reads the URL, headers and body, turns them into method arguments, calls your method and writes the return value back as the response.

A mental model

How it works

@RestController marks a class whose methods return data directly. @GetMapping("/orders/{id}") binds a method to GET requests for that path.

Arguments are filled from the request: @PathVariable takes a piece of the URL, @RequestParam a query parameter, @RequestBody the body (parsed from JSON into an object by Jackson), and @RequestHeader a header.

The return value is converted to JSON and sent with status 200, unless you return ResponseEntity (full control of status and headers) or annotate with @ResponseStatus.

@ExceptionHandler or @RestControllerAdvice turns exceptions into proper error responses in one place instead of try/catch in every method.

Going deeper

Keep controllers thin: validate input, call a service, shape the response. Business rules and transactions belong in the service layer, which is also easier to test.

Add @Valid with bean validation annotations (@NotNull, @Size) on @RequestBody objects; failures produce a 400 automatically. Never trust the client for anything.

Return DTOs, not JPA entities. Entities drag lazy relations (serialization errors or accidental queries) and leak columns you never meant to expose.

Under the hood

A single DispatcherServlet receives every request, asks HandlerMapping which method matches, and delegates to HandlerAdapter, which resolves each argument with HandlerMethodArgumentResolvers and writes the result with HttpMessageConverters (Jackson for JSON).

Common mistakes

Business logic in the controller.
Returning entities directly.
Skipping validation on request bodies.
Catching exceptions everywhere instead of one advice class.

How Unravel recognises it

When you paste code, Unravel looks for these signs of spring rest controllers. Spotting them yourself is a good habit when you read unfamiliar code:

Annotations: @RestController @Controller @RequestMapping @GetMapping @PostMapping @PutMapping @DeleteMapping @PatchMapping @RequestBody @PathVariable @RequestParam @ResponseStatus @ExceptionHandler @ControllerAdvice and 1 more
Types: ResponseEntity

Part of a learning path

How a Spring request really works · previous: Jackson JSON · next: Bean validation (@Valid)
Building and documenting APIs · next: OpenAPI and Swagger documentation

Related concepts

Jackson JSONI/O and data Spring beans and dependency injectionSpring @TransactionalSpring

Builds on this

Bean validation (@Valid)Spring Central error handling and ProblemDetailSpring Streaming responses and Server-Sent EventsSpring File upload and downloadI/O and data OpenAPI and Swagger documentationSpring GraphQL serversSpring

Frequently asked questions

What is Spring REST controllers?

A controller maps HTTP requests to Java methods. Spring reads the URL, headers and body, turns them into method arguments, calls your method and writes the return value back as the response.

What are the most common mistakes with Spring REST controllers?

Business logic in the controller. Returning entities directly. Skipping validation on request bodies. Catching exceptions everywhere instead of one advice class.

How can I see Spring REST controllers in real code?

Paste your own Java into Unravel and it will point out where spring rest controllers appears, explain how it works at the detail level you choose, and draw the flow of the code around it.