What is native API versioning in Spring Boot 4 and how do you use it?

API versioning has historically been one of the most DIY aspects of Spring development -- teams built custom URL paths, header filters, or RequestCondition hacks. Spring Framework 7 (and Spring Boot 4) makes API versioning a first-class feature with native annotation-based support in both Spring MVC and WebFlux.

// Spring Boot 3: manual versioning (repetitive and fragile)
@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 { ... }

@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 { ... }

// Spring Boot 4: native versioning
@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping(path = "/{id}", version = "1.0")
    public ProductV1 getProductV1(@PathVariable String id) {
        return productService.findV1(id);
    }

    @GetMapping(path = "/{id}", version = "2.0")
    public ProductV2 getProductV2(@PathVariable String id) {
        return productService.findV2(id);
    }
}

// Configuration in application.properties:
# Header-based versioning:
spring.mvc.apiversion.use-header=X-API-Version
spring.mvc.apiversion.default=1
# Request: GET /api/products/123 with header X-API-Version: 2
# Routes to: getProductV2

// Deprecation handling (RFC 9745 compliant):
@GetMapping(path = "/{id}", version = "1.0", deprecated = true)
public ProductV1 getProductV1(@PathVariable String id) {
    // Spring automatically adds Deprecation response header
    return productService.findV1(id);
}

RFC 9745 compliance: Spring Boot 4 automatically adds the Deprecation HTTP response header when a versioned endpoint is marked as deprecated, giving API consumers programmatic notification of deprecation without custom filter code.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.