@PathVariable vs @RequestParam vs @RequestBody vs @RequestHeader.

These four annotations each pull data from a different part of the HTTP request — the trick is knowing which part. A HandlerMethodArgumentResolver reads the annotation, extracts the right slice of the request, converts it to your parameter type, and passes it in.

@PathVariable — from the URL template

Binds a segment of the path declared with {...} in the mapping. Used for resource identity.

@GetMapping("/orders/{id}/items/{itemId}")
Item get(@PathVariable Long id, @PathVariable Long itemId) { ... }

The name must match the template variable (or be given explicitly). Path variables are inherently part of the URL, so they're never optional in a meaningful sense.

@RequestParam — from the query string (or form body)

Binds ?key=value query parameters, or application/x-www-form-urlencoded form fields. Used for filtering, paging, flags.

@GetMapping("/orders")
List<OrderDto> list(@RequestParam(defaultValue = "0") int page,
                    @RequestParam(required = false) String status) { ... }

Supports required, defaultValue, collections (?tag=a&tag=b → List<String>), and Map<String,String> for all params.

@RequestBody — from the request body, deserialized

Takes the entire body and runs it through an HttpMessageConverter (Jackson for JSON) to produce an object. There can be only one per method — there's one body.

@PostMapping("/orders")
OrderDto create(@Valid @RequestBody CreateOrder cmd) { ... }

Pair it with @Valid to trigger Bean Validation on the deserialized object.

@RequestHeader — from an HTTP header

Binds a single header value, or all headers as a Map/HttpHeaders.

@GetMapping("/orders")
List<OrderDto> list(@RequestHeader("Authorization") String auth,
                    @RequestHeader(value = "X-Trace-Id", required = false) String trace) { ... }

The mental table