REST Controllers

A REST controller receives HTTP requests, calls your service layer and returns data (usually JSON). Spring Boot converts Java objects to JSON and back automatically.

Mapping annotations

Complete controller

import java.net.URI;
import java.util.*;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

public record Product(Long id, String name, double price) { }

@RestController
@RequestMapping("/api/products")
public class ProductController {

    private final Map<Long, Product> store = new LinkedHashMap<>();
    private final AtomicLong ids = new AtomicLong();

    @GetMapping                                            // GET /api/products?minPrice=10
    public List<Product> list(@RequestParam(defaultValue = "0") double minPrice) {
        return store.values().stream().filter(p -> p.price() >= minPrice).toList();
    }

    @GetMapping("/{id}")                                   // GET /api/products/5
    public ResponseEntity<Product> get(@PathVariable Long id) {
        Product p = store.get(id);
        return p == null ? ResponseEntity.notFound().build() : ResponseEntity.ok(p);
    }

    @PostMapping                                           // POST /api/products  (JSON body)
    public ResponseEntity<Product> create(@RequestBody Product input) {
        Product saved = new Product(ids.incrementAndGet(), input.name(), input.price());
        store.put(saved.id(), saved);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                .path("/{id}").buildAndExpand(saved.id()).toUri();
        return ResponseEntity.created(location).body(saved);   // 201 + Location header
    }

    @PutMapping("/{id}")
    public ResponseEntity<Product> update(@PathVariable Long id, @RequestBody Product input) {
        if (!store.containsKey(id)) return ResponseEntity.notFound().build();
        Product updated = new Product(id, input.name(), input.price());
        store.put(id, updated);
        return ResponseEntity.ok(updated);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        return store.remove(id) == null ? ResponseEntity.notFound().build() : ResponseEntity.noContent().build();
    }
}

curl -X POST localhost:8080/api/products -H "Content-Type: application/json" -d '{"name":"Pen","price":10}'
curl localhost:8080/api/products
curl -X DELETE localhost:8080/api/products/1

Important HTTP status codes

Other request features

• @RequestHeader reads a header, @CookieValue reads a cookie.
• @RequestMapping(produces = 'application/json', consumes = 'application/json') restricts media types.
• Pageable parameter: /api/products?page=0&size=10&sort=price,desc works with Spring Data.
• @ResponseStatus(HttpStatus.CREATED) sets a fixed status.
• Spring Framework 7 (Boot 4) adds built-in API versioning support for paths, headers and parameters.

How Spring binds arguments and writes the result

Content negotiation

@GetMapping(value = "/api/products/{id}", produces = { MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE })
public Product get(@PathVariable Long id) { return service.get(id); }
// Accept: application/json  -> JSON       Accept: application/xml -> XML (needs jackson-dataformat-xml)
// No matching type -> 406 Not Acceptable      Body in a wrong Content-Type -> 415 Unsupported Media Type

Conditional GET with ETag (saves bandwidth)

@GetMapping("/api/products/{id}")
public ResponseEntity<ProductResponse> get(@PathVariable Long id, WebRequest request) {
    ProductResponse product = service.get(id);
    String etag = "\"" + product.version() + "\"";
    if (request.checkNotModified(etag)) {            // compares If-None-Match with the ETag
        return null;                                 // Spring sends 304 Not Modified with an empty body
    }
    return ResponseEntity.ok().eTag(etag).cacheControl(CacheControl.maxAge(Duration.ofMinutes(1))).body(product);
}

Async return types

@GetMapping("/api/reports/{id}")
public CompletableFuture<Report> report(@PathVariable Long id) {
    return CompletableFuture.supplyAsync(() -> reportService.build(id), executor);     // servlet thread is free while it runs
}

@GetMapping("/api/slow")
public Callable<String> slow() {
    return () -> { Thread.sleep(2000); return "done"; };          // runs on the MVC async executor
}
// spring.mvc.async.request-timeout=30s

HTTP semantics to respect

API design rules that age well

• Nouns and plurals in paths: /api/orders/42/items, not /api/getOrderItems.
• Use query parameters for filtering, sorting and paging: /api/orders?status=PAID&sort=createdAt,desc&page=0&size=20.
• Version deliberately (/api/v1/... or a header). Never change the meaning of existing fields.
• Return DTOs, not entities. Use one error format (ProblemDetail).
• Make POST safe to retry with an Idempotency-Key header for payments and orders.
• Always paginate collections and cap the page size (for example max 100).

Common mistake: Returning entities directly from controllers. It exposes your database structure and can trigger lazy loading errors. Return DTOs (records) instead.

Interview questions

What is the difference between @Controller and @RestController?

@RestController adds @ResponseBody to every method, so return values are written to the response body (JSON) instead of being treated as view names.

What is the difference between PUT and PATCH?

PUT replaces the whole resource. PATCH changes only some fields.

@RequestParam or @PathVariable?

@PathVariable reads a part of the URL path (/products/5). @RequestParam reads a query parameter (?page=2).

How do I return 201 with a Location header?

Use ResponseEntity.created(uri).body(dto). Build the uri from the request with ServletUriComponentsBuilder.

Why does a request with a wrong JSON field type return 400?

Jackson throws HttpMessageNotReadableException while reading the body. Spring maps it to 400. You can customize the response in @RestControllerAdvice.