Spring REST API Versioning: The Complete Guide (2024 Edition)

Let me be blunt: API versioning is one of the most misunderstood topics in REST architecture. I've seen teams spend weeks debating it, only to ship something that breaks production on day one. This isn't academic — it's about keeping your payment system running while you roll out new features. Spring Boot 3.2+ gives you several ways to handle this, but most developers pick the wrong one. Here's the hard truth: most teams get this wrong because they treat versioning as a technical problem when it's really a contract negotiation with your clients.

1. Why Versioning Matters (And Why You'll Regret Skipping It)

Stop pretending your API won't change. It will. The moment you have a single client in production, you've made an implicit contract. Breaking that contract is not just bad practice — it's a breach of trust that can cost you customers and money. In Spring Boot, versioning isn't hard, but doing it right requires understanding the trade-offs. I've seen this blow up in production when teams used request parameter versioning like ?version=1. It works until it doesn't — caching proxies and CDNs treat those as different URLs, but your API gateway might not. The result? Stale data served to clients who think they're getting the latest version. Always version at the infrastructure level, not the application level.

package com.example.payment.v1;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/payments")
public class PaymentControllerV1 {

    @PostMapping
    public PaymentResponse processPayment(@RequestBody PaymentRequest request) {
        // V1 logic: supports only credit cards
        return new PaymentResponse(request.transactionId(), "PENDING");
    }

    record PaymentRequest(String transactionId, String cardNumber, double amount) {}
    record PaymentResponse(String transactionId, String status) {}
}

2. What the Official Docs Won't Tell You

The Spring Boot documentation is great for getting started, but it won't tell you that header versioning can be a nightmare in production. Let me be blunt: if you're using Accept header versioning with custom media types like application/vnd.myapp.v1+json, you're setting yourself up for pain. The issue? Most API clients don't set Accept headers correctly. I've debugged countless cases where browsers or mobile apps send / as the Accept header, which causes Spring to fall back to the first matching handler — often the wrong version. The official docs recommend WebMvcConfigurer for custom header parsing, but they don't warn you about the HttpMediaTypeNotAcceptableException that will haunt your logs. Instead, use a custom HandlerInterceptor to explicitly parse version headers and route accordingly. This gives you full control and proper error handling.

package com.example.config;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.servlet.HandlerInterceptor;

public class VersionInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String version = request.getHeader("X-API-Version");
        if (version == null || version.isBlank()) {
            version = "1"; // default to latest stable
        }
        request.setAttribute("apiVersion", version);
        return true;
    }
}

3. URI Path Versioning: The Simplest (and Most Reliable) Approach

URI path versioning is the gold standard for public APIs. It's explicit, cache-friendly, and easy to debug. When you see /v1/orders and /v2/orders, there's no ambiguity. In Spring Boot 3.2, you implement this by creating separate controller classes for each version. Stop doing the "one controller with if-else" pattern. That's a trap that will burn you. I've seen a codebase where a single OrderController had 15 methods, each with if (version == 1) ... else if (version == 2) .... It was unmaintainable. Instead, use separate packages: com.example.orders.v1 and com.example.orders.v2. Each has its own @RestController with @RequestMapping("/api/v1/orders") and @RequestMapping("/api/v2/orders"). This keeps your code clean and your deployments safe. You can even deploy different versions to different servers if needed.

package com.example.orders.v2;

import org.springframework.web.bind.annotation.*;

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

    @PostMapping
    public OrderResponse createOrder(@RequestBody OrderRequest request) {
        // V2 supports multiple payment methods
        return new OrderResponse(request.orderId(), "CONFIRMED", request.paymentMethod());
    }

    record OrderRequest(String orderId, String paymentMethod, double total) {}
    record OrderResponse(String orderId, String status, String paymentMethod) {}
}

4. Accept Header Versioning: When to Use It (and When to Run Away)

Accept header versioning is elegant for internal microservices where you control both sides. You send Accept: application/vnd.myapp.v2+json and get the right version. But here's the hard truth: most teams get this wrong because they don't handle the / wildcard. I've seen this blow up in production when a new microservice started sending Accept: / and Spring matched the wrong controller. The fix? Implement a custom WebMvcConfigurer that parses the Accept header and throws a clear error if the version is ambiguous. Spring Boot 3.2+ has improved this with ContentNegotiationConfigurer, but you still need to be explicit. Never rely on default behavior. If you're doing Accept header versioning without a custom HandlerInterceptor, you're doing it wrong. The risk is too high for production systems handling payments or user data.

package com.example.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
            .favorParameter(false)
            .ignoreAcceptHeader(false)
            .defaultContentType(MediaType.APPLICATION_JSON)
            .mediaType("v1", MediaType.valueOf("application/vnd.myapp.v1+json"))
            .mediaType("v2", MediaType.valueOf("application/vnd.myapp.v2+json"));
    }
}

5. Request Parameter Versioning: Why You Should Never Use It

Let me be blunt: request parameter versioning (?version=1) is a trap that will burn you. It seems simple, but it breaks every caching layer in existence. CDNs like Cloudflare and Akamai treat ?version=1 and ?version=2 as different cache keys, which is fine. But the problem is that many API gateways and load balancers strip query parameters, causing version information to be lost. I've seen this blow up in production when a team used ?version=1 and their NGINX reverse proxy was configured to ignore query parameters for caching. Clients got the wrong version randomly. The fix was to move to URI path versioning, but by then, the damage was done — 2 days of data corruption. Spring Boot 3.2+ supports request parameter versioning via @RequestParam, but just because you can doesn't mean you should. If you're using request parameter versioning in a public API, you're doing it wrong. Period.

// NEVER DO THIS IN PRODUCTION
@RestController
@RequestMapping("/api/orders")
public class BadExampleController {

    @GetMapping
    public List<Order> getOrders(@RequestParam(defaultValue = "1") int version) {
        if (version == 1) {
            return orderService.getOrdersV1();
        } else if (version == 2) {
            return orderService.getOrdersV2();
        }
        throw new IllegalArgumentException("Unsupported version: " + version);
    }
}

6. Custom Versioning Strategy: Building a Version Router

Sometimes the standard approaches don't fit. Maybe you need to version based on a custom header, or route based on client IP range. Spring Boot 3.2+ allows you to build a custom version router using HandlerInterceptor and WebMvcConfigurer. This is advanced, but it's the only way to handle complex scenarios like A/B testing or gradual rollouts. I've built this for a real-time analytics platform where different data centers needed different API versions. The key is to implement a HandlerInterceptor that reads the version from a header, cookie, or even a JWT claim, then sets a request attribute. Your controllers can then check this attribute. But be careful: custom versioning is a double-edged sword. It's flexible, but it's also hard to document and debug. Only use this when URI path or header versioning doesn't work. Otherwise, you're over-engineering.

package com.example.config;

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
public class CustomVersionRouter implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String version = request.getHeader("X-API-Version");
        if (version == null) {
            // Fallback to cookie
            version = request.getCookies() != null ? 
                Arrays.stream(request.getCookies())
                    .filter(c -> "api_version".equals(c.getName()))
                    .map(Cookie::getValue)
                    .findFirst().orElse("1") : "1";
        }
        request.setAttribute("apiVersion", version);
        return true;
    }
}

7. Versioning with Spring Cloud Gateway

If you're using Spring Cloud Gateway (3.1.x+), you can handle versioning at the gateway level before requests reach your microservices. This is powerful because it centralizes version routing and allows you to migrate traffic gradually. For example, you can route 10% of traffic to /v2/orders and 90% to /v1/orders using weight-based routing. Spring Cloud Gateway supports this via the Weight route predicate. But here's the hard truth: most teams get this wrong because they forget to add version information to the downstream request. If you strip the version at the gateway, your microservices won't know which version to serve. Always add a header like X-Version-Routed before forwarding. I've seen this blow up in production when a team routed traffic to the wrong microservice because the gateway didn't preserve the version context.

spring:
  cloud:
    gateway:
      routes:
        - id: orders-v1
          uri: http://orders-service:8080
          predicates:
            - Path=/api/v1/orders/**
          filters:
            - AddRequestHeader=X-Version-Routed, v1
        - id: orders-v2
          uri: http://orders-service:8080
          predicates:
            - Path=/api/v2/orders/**
          filters:
            - AddRequestHeader=X-Version-Routed, v2
        - id: orders-weighted
          uri: http://orders-service:8080
          predicates:
            - Path=/api/orders/**
            - Weight=orders-group, 10  # 10% to V2
          filters:
            - AddRequestHeader=X-Version-Routed, v2

8. Testing and Deprecating API Versions

Versioning without testing is like deploying without a parachute. You need integration tests that explicitly test each version. In Spring Boot 3.2, use @WebMvcTest with separate test classes for each version controller. But more importantly, test the version routing itself. I've seen teams write perfect controller tests but forget to test that the version header actually routes to the correct controller. For deprecation, always add a Sunset header and a Deprecation header to old versions. Spring Boot doesn't do this automatically — you need a custom filter. I've seen this blow up in production when a team deprecated a version but forgot to add the headers. Clients had no warning, and when the endpoint was removed, they broke. Stop ignoring deprecation headers. They're not optional. If you're deprecating an API without a sunset policy and client notification, you're doing it wrong.

package com.example.config;

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import java.io.IOException;
import java.time.LocalDate;

@Component
public class DeprecationFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletResponse httpResponse = (HttpServletResponse) response;
        String path = ((jakarta.servlet.http.HttpServletRequest) request).getRequestURI();
        
        if (path.startsWith("/api/v1/")) {
            httpResponse.setHeader("Deprecation", "true");
            httpResponse.setHeader("Sunset", "Sat, 31 Dec 2024 23:59:59 GMT");
        }
        chain.doFilter(request, response);
    }
}