Spring MVC and REST controllers

Every request to a Spring MVC application enters one servlet, the DispatcherServlet (a front controller). It asks its handler mappings which controller method matches the request, invokes that method with arguments resolved from the request, and writes the return value back as the response body.

@RestController
@RequestMapping("/orders")
class OrderController {

    @GetMapping("/{id}")
    OrderDto get(@PathVariable long id) { ... }

    @GetMapping
    List<OrderDto> list(@RequestParam(defaultValue = "0") int page) { ... }

    @PostMapping(consumes = "application/json")
    ResponseEntity<OrderDto> create(@RequestBody @Valid NewOrder body) {
        OrderDto saved = service.create(body);
        return ResponseEntity.created(URI.create("/orders/" + saved.id())).body(saved);
    }
}

@RestController is @Controller plus @ResponseBody: return values are serialised into the body (by Jackson, through an HttpMessageConverter) instead of being treated as view names. @PathVariable binds a {segment} of the path, @RequestParam a query parameter, and @RequestBody deserialises the body. Return a plain object for 200 OK, or a ResponseEntity when you need to choose the status and headers — 201 Created with a Location header for a POST that creates something.

Which mapping wins

Several patterns can match one path: /orders/{id} and /orders/export both match /orders/export. Spring does not take the first declared mapping; it compares the matches and picks the most specific. A literal segment is more specific than a {variable}, so /orders/export wins regardless of the order the methods appear in.

1import java.util.*;2 3public class Solution {4    record Mapping(String method, String pattern, String handler) {}5 6    static Map<String, String> match(String pattern, String path) {7        String[] p = pattern.split("/", -1), s = path.split("/", -1);8        if (p.length != s.length) return null;9        Map<String, String> vars = new LinkedHashMap<>();10        for (int i = 0; i < p.length; i++) {11            if (p[i].startsWith("{")) vars.put(p[i].substring(1, p[i].length() - 1), s[i]);12            else if (!p[i].equals(s[i])) return null;13        }14        return vars;15    }16 17    static String dispatch(List<Mapping> mappings, String method, String path) {18        Mapping best = null; Map<String, String> bestVars = null;19        Set<String> allowed = new TreeSet<>();20        for (Mapping m : mappings) {21            Map<String, String> vars = match(m.pattern(), path);22            if (vars == null) continue;23            allowed.add(m.method());24            if (!m.method().equals(method)) continue;25            if (best == null || vars.size() < bestVars.size()) { best = m; bestVars = vars; }26        }27        if (best != null) return method + " " + path + " -> 200 " + best.handler() + bestVars;28        if (!allowed.isEmpty()) return method + " " + path + " -> 405, Allow: " + String.join(", ", allowed);29        return method + " " + path + " -> 404";30    }31 32    public static List<String> run() {33        List<Mapping> mappings = List.of(34            new Mapping("GET", "/orders/{id}", "getOrder"),        // declared first35            new Mapping("GET", "/orders/export", "exportOrders"),36            new Mapping("POST", "/orders", "createOrder"));37        return List.of(38            dispatch(mappings, "GET", "/orders/42"),39            dispatch(mappings, "GET", "/orders/export"),40            dispatch(mappings, "DELETE", "/orders/42"),41            dispatch(mappings, "GET", "/orders"),42            dispatch(mappings, "GET", "/customers"));43    }44}

Since Spring Framework 6, trailing-slash matching is off by default: /orders/ no longer matches a mapping for /orders.

When nothing matches, the status says why

• 404 Not Found — no mapping matches the path at all.
• 405 Method Not Allowed — the path matches, but not with this HTTP method. The response carries an Allow header listing the methods that would work.
• 415 Unsupported Media Type — the method matched but the request's Content-Type is not in the mapping's consumes.
• 406 Not Acceptable — nothing the handler can produce satisfies the request's Accept header.
• 400 Bad Request — a handler was found but its arguments could not be bound: a required @RequestParam is missing, /orders/abc cannot become a long, or the JSON body does not parse. Matching is textual — {id} matches abc — and conversion happens only after the handler is chosen. Put a regex in the pattern, /orders/{id:\d+}, and /orders/abc no longer matches that mapping; with nothing else mapped there, it is a 404.

Telling these apart is a large part of debugging an API: a 405 means your path is right and your verb is wrong; a 404 means the path itself is not mapped (check the class-level prefix and the context path).