Spring MVC & Building REST APIs

Returning a plain object from an @RestController method always results in an HTTP 200 OK (aside from a few framework-level conventions, like a void method combined with certain annotations), with no direct way to customize the status code or add response headers from within that return statement:

@GetMapping("/orders/{id}")
Order getOrder(@PathVariable Long id) {
    return repository.findById(id).orElse(null); // always 200, even if null body is returned!
}

ResponseEntity<T> wraps the response body together with an explicit status code and headers, giving full control over the actual HTTP response:

@GetMapping("/orders/{id}")
ResponseEntity<Order> getOrder(@PathVariable Long id) {
    return repository.findById(id)
        .map(ResponseEntity::ok)                          // 200 with the order
        .orElse(ResponseEntity.notFound().build());        // 404, no body
}

@PostMapping("/orders")
ResponseEntity<Order> createOrder(@RequestBody @Valid CreateOrderRequest request) {
    Order created = service.create(request);
    URI location = URI.create("/orders/" + created.getId());
    return ResponseEntity.created(location).body(created); // 201 + Location header
}

@DeleteMapping("/orders/{id}")
ResponseEntity<Void> deleteOrder(@PathVariable Long id) {
    service.delete(id);
    return ResponseEntity.noContent().build();              // 204, no body
}

When to reach for ResponseEntity: whenever the status code should genuinely vary based on outcome (200 vs. 404 vs. 201 vs. 204), or when you need to set specific response headers (Location, ETag, Cache-Control) explicitly. For simple, always-successful endpoints where a flat 200 with a JSON body is genuinely all that's needed, returning the plain object directly is simpler and perfectly idiomatic — ResponseEntity is a tool for when the response's metadata (status/headers) needs to be a first-class, controllable part of the method's logic, not a default you should reach for on every single endpoint regardless of need.

Both let you run logic around a request's processing, but they operate at different layers of the stack:

Servlet Filter (part of the raw Servlet API, jakarta.servlet.Filter) sits in front of the entire servlet container's dispatch mechanism — including, but not limited to, Spring's DispatcherServlet. A filter runs before Spring MVC even gets involved, and has no visibility into which controller/handler method will eventually process the request:

@Component
class RequestLoggingFilter implements Filter {
    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        System.out.println("Incoming: " + ((HttpServletRequest) req).getRequestURI());
        chain.doFilter(req, res); // must explicitly continue the chain
    }
}

HandlerInterceptor (org.springframework.web.servlet.HandlerInterceptor) operates inside Spring MVC's own dispatch process, specifically around the invocation of a resolved handler — it has access to the actual HandlerMethod object (the controller and method that will run), and integrates naturally with Spring's DI:

@Component
class AuthInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
        if (handler instanceof HandlerMethod hm && hm.hasMethodAnnotation(RequiresAuth.class)) {
            // check auth specifically for annotated handler methods
        }
        return true; // false would short-circuit the request here
    }
}

Registered via a WebMvcConfigurer:

@Configuration
class WebConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new AuthInterceptor()).addPathPatterns("/api/**");
    }
}

Practical distinctions:

• Scope of applicability: a Filter applies to any request reaching the servlet container (static resources, other servlets, etc.), while a HandlerInterceptor only applies to requests actually dispatched to Spring MVC handlers.
• Framework awareness: a HandlerInterceptor knows which controller method will run (useful for annotation-driven logic, like checking a custom @RequiresAuth annotation on the target method); a Filter only sees the raw request/response.
• Dependency injection: a HandlerInterceptor, being a Spring-managed bean, naturally injects other Spring beans; a Filter can too if registered as a Spring bean, but it's conceptually a servlet-container-level construct, existing independently of Spring MVC.

When to use which: use a Filter for concerns that should apply broadly at the servlet level regardless of Spring MVC specifics (e.g., request/response encoding, broad security header injection, basic request logging); use a HandlerInterceptor when the logic specifically needs to know about — or run just before/after — a Spring MVC handler method.

CORS (Cross-Origin Resource Sharing) is a browser-enforced security mechanism: by default, a webpage served from one origin (https://app.example.com) cannot make a JavaScript-initiated request to a different origin's API (https://api.example.com) unless that API explicitly opts in via specific Access-Control-* response headers. Spring Boot provides a few ways to configure this opt-in.

1. Per-controller/method with @CrossOrigin:

@RestController
@CrossOrigin(origins = "https://app.example.com")
class OrderController {
    @GetMapping("/orders")
    List<Order> listOrders() { ... } // this endpoint allows cross-origin requests from that origin
}

2. Globally, via a WebMvcConfigurer (the more common approach for an entire API):

@Configuration
class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins("https://app.example.com")
            .allowedMethods("GET", "POST", "PUT", "DELETE")
            .allowedHeaders("*")
            .allowCredentials(true);
    }
}

3. Via a CorsFilter bean — useful when CORS needs to be applied even earlier, e.g., ahead of Spring Security's filter chain, since Spring Security's own filters can otherwise reject a request (including its CORS preflight OPTIONS request) before it ever reaches Spring MVC's CORS handling.

Important interaction with Spring Security: if Spring Security is on the classpath, it has its own CORS configuration hook (http.cors(Customizer.withDefaults()) in a SecurityFilterChain), which needs to be wired to the same CorsConfigurationSource — configuring CORS only at the Spring MVC level, without also enabling it in Spring Security's filter chain, is a common source of confusing "CORS is configured but requests still get blocked" issues, since Security's filters run before Spring MVC's own CORS handling would ever be reached.

Common mistakes: using allowedOrigins("*") together with allowCredentials(true) is invalid per the CORS spec and browsers will reject it — a wildcard origin cannot be combined with credentialed requests; you must list explicit origins (or use allowedOriginPatterns for pattern-based matching) if credentials are involved.

As a REST API evolves, breaking changes (renaming/removing a field, changing behavior) need a way to coexist with clients still using an older contract. Several strategies are common in Spring-based APIs:

1. URI versioning — embed the version directly in the path:

@RestController
@RequestMapping("/api/v1/orders")
class OrderControllerV1 { ... }

@RestController
@RequestMapping("/api/v2/orders")
class OrderControllerV2 { ... }

Simplest to implement and most discoverable/visible to API consumers (and easy to route, cache, and document per version), but clutters the URL, and strict REST purists argue a resource's URI shouldn't encode something as orthogonal as its representation's version.

2. Header versioning — a custom request header carries the version, URL stays stable:

@GetMapping(value = "/orders", headers = "Api-Version=2")
List<OrderV2> listOrdersV2() { ... }

Keeps URLs clean, but is less visible/discoverable (you can't just paste a URL into a browser to see a specific version) and slightly more effort to test/document.

3. Media type (content negotiation) versioning — the version lives inside a custom Accept header value:

@GetMapping(value = "/orders", produces = "application/vnd.company.app-v2+json")
List<OrderV2> listOrdersV2() { ... }

Considered the most "RESTful" by strict HATEOAS/content-negotiation advocates, but the least ergonomic for typical API consumers and tooling.

4. Query parameter versioning:

@GetMapping(value = "/orders", params = "version=2")
List<OrderV2> listOrdersV2() { ... }

Simple, but easy to omit accidentally (defaulting to some implicit version) and considered less clean than the path-based approach by many API design guides.

In practice: URI versioning is by far the most common choice for public and internal APIs alike, largely for its simplicity, visibility in logs/monitoring, and ease of routing at the infrastructure level (a load balancer or API gateway can trivially route /api/v1/* vs /api/v2/* to different backend deployments) — despite being the "least RESTful" option in a strict theoretical sense.

Content negotiation is how Spring MVC decides which representation format to serialize a response body into, when a resource could potentially be returned as JSON, XML, or something else.

Primary mechanism — the Accept request header: the client states what media types it can handle, in preference order:

GET /api/orders/42
Accept: application/json

Spring MVC consults its registered HttpMessageConverters (Jackson's JSON converter is registered by default when spring-boot-starter-web is on the classpath) to find one that both understands the response's Java type and can produce a media type matching the client's Accept header — Jackson producing application/json satisfies that request.

@GetMapping(value = "/orders/{id}", produces = { "application/json", "application/xml" })
Order getOrder(@PathVariable Long id) { ... }
// same handler can serve either representation, depending on the client's Accept header

If no registered converter can produce any media type the client says it will accept, Spring MVC responds with 406 Not Acceptable.

Alternative negotiation strategies (less common, and generally discouraged in modern API design in favor of the Accept header alone):

• Path extension (/orders/42.json / /orders/42.xml) — historically supported but disabled by default in modern Spring Boot, partly due to security concerns (URL-extension-based negotiation has been a source of exploits in some frameworks) and ambiguity with actual resource paths containing dots.
• Query parameter (/orders/42?format=json) — can be enabled via ContentNegotiationConfigurer, but similarly less idiomatic than relying on the standard Accept header.

In practice for most modern REST APIs: since virtually all clients and APIs standardize on JSON, explicit content negotiation configuration is rarely a major concern day-to-day — Jackson's JSON converter, registered automatically by Spring Boot's auto-configuration, handles the overwhelming majority of real-world traffic without any extra setup, and content negotiation mainly becomes an explicit topic when an API genuinely needs to support multiple formats (e.g., JSON and XML) for different classes of clients.

@RequestMapping is the original, general-purpose mapping annotation — it can map a class or method to a URL path, and (without further attributes) matches any HTTP method unless you explicitly restrict it:

@RequestMapping(value = "/orders", method = RequestMethod.GET)
List<Order> listOrders() { ... }

@RequestMapping(value = "/orders", method = RequestMethod.POST)
Order createOrder(@RequestBody CreateOrderRequest request) { ... }

Since Spring 4.3, the shortcut annotations — @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping — are provided as composed meta-annotations, each equivalent to @RequestMapping pre-configured for exactly one HTTP method:

@GetMapping("/orders")
List<Order> listOrders() { ... }

@PostMapping("/orders")
Order createOrder(@RequestBody CreateOrderRequest request) { ... }

Functionally identical to the @RequestMapping(method = ...) form, but more concise and — importantly — communicates the intended HTTP method at a glance, without needing to read the method attribute to know what verb a handler responds to.

Class-level @RequestMapping is still commonly used to declare a shared base path for all methods in a controller, combined with method-level shortcut annotations for the actual verbs:

@RestController
@RequestMapping("/api/orders") // shared prefix
class OrderController {
    @GetMapping         // GET /api/orders
    List<Order> list() { ... }

    @GetMapping("/{id}") // GET /api/orders/{id}
    Order get(@PathVariable Long id) { ... }

    @PostMapping        // POST /api/orders
    Order create(@RequestBody CreateOrderRequest req) { ... }
}

Rule of thumb: use the HTTP-method-specific shortcut annotations for individual handler methods (the modern, idiomatic default); reserve plain @RequestMapping for class-level base-path declarations, or the rare case where a single handler genuinely needs to respond to multiple HTTP methods at once.