Why this matters
- Mapping annotations are the daily vocabulary of BookStore API development — knowing the full toolkit avoids workarounds and bugs.
- Incorrect binding (missing
@RequestBody, wrong@PathVariablename) causes silent 400 errors or null parameters. - HTTP semantics (status codes, content types) belong in the controller layer, not services.
@RestController
L1 · FresherCombines @Controller and @ResponseBody — return values serialize to JSON via Jackson by default.
HTTP method mappings
L2 · Intermediate@GetMapping, @PostMapping, and friends bind verbs and paths. Use @PathVariable and @RequestParam for URL parts and query strings.
ResponseEntity
L3 · AdvancedReturn ResponseEntity to set status codes, headers, and body explicitly — required for 201 Created with Location headers on BookStore orders.
Content negotiation
L4 · Expertproduces and consumes restrict media types. Prefer JSON defaults; add XML or protobuf only when clients require it.
Core mapping annotations
// learn:fragment
@RestController
@RequestMapping("/api/books")
public class BookController {
private final BookService bookService;
public BookController(BookService bookService) {
this.bookService = bookService;
}
@GetMapping
public List<BookResponse> list(
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size) {
return bookService.findAll(page, size);
}
@GetMapping("/{id}")
public BookResponse get(@PathVariable Long id) {
return BookResponse.from(bookService.findById(id));
}
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public BookResponse create(@RequestBody CreateBookRequest request) {
return BookResponse.from(bookService.create(request));
}
@PutMapping("/{id}")
public BookResponse update(@PathVariable Long id,
@RequestBody UpdateBookRequest request) {
return BookResponse.from(bookService.update(id, request));
}
@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
bookService.delete(id);
}
}
Binding annotations
@PathVariable— URI segment:/api/books/{id}→Long id.@RequestParam— Query string:?genre=fiction→String genre.@RequestBody— Deserialise JSON body to a Java object.@RequestHeader— Read an HTTP header value.@ResponseStatus— Set HTTP status without returningResponseEntity.
ResponseEntity for full control
When you need custom headers or conditional status codes:
@GetMapping("/{id}")
public ResponseEntity<BookResponse> get(@PathVariable Long id) {
return bookService.findById(id)
.map(book -> ResponseEntity.ok(BookResponse.from(book)))
.orElse(ResponseEntity.notFound().build());
}
ResponseEntity wraps body, status, and headers in one return type.
The rest of this guide is part of Pro
Free covers every fresher guide in full. Pro unlocks Senior, Staff and Architect guides across every track.
Still to come · 7 sections
- Status code families
- Content negotiation
- Path variable patterns
- Request body with validation
- HTTP method semantics
- Class-level vs method-level mapping
- CORS preflight
Test yourself
Answer these before moving on — recall is what makes it stick.