Spring Boot Rest API Versioning

REST API versioning is a technique used to manage changes in APIs over time without breaking existing client applications. In real-world applications, APIs evolve due to new features, bug fixes, or changes in business requirements. Versioning allows multiple versions of an API to coexist safely.

Why Do We Need API Versioning?

• To avoid breaking existing client applications
• To introduce new features without affecting old consumers
• To support backward compatibility
• To allow gradual migration to newer API versions
• To maintain stable contracts for external clients

Without versioning, any change in request or response structure can break clients that depend on the API.

Common API Versioning Strategies in Spring Boot

Spring Boot supports multiple API versioning strategies:

1. URI Path Versioning
2. Request Parameter Versioning
3. Header-Based Versioning
4. Content Negotiation (Media Type) Versioning

1. URI Path Versioning

This is the most commonly used and simplest approach. The API version is included directly in the URL path.

Example URLs

• /api/v1/users
• /api/v2/users

Spring Boot Controller Example

    @RestController
    @RequestMapping("/api")
    public class UserController {
    
        @GetMapping("/v1/users")
        public String getUsersV1() {
            return "Users from API Version 1";
        }
    
        @GetMapping("/v2/users")
        public String getUsersV2() {
            return "Users from API Version 2";
        }
    }
    

Pros

• Easy to understand and implement
• Clear visibility of API version
• Easy to test and debug

Cons

• URL changes for every new version
• Not considered fully RESTful by some purists

2. Request Parameter Versioning

In this approach, the API version is passed as a query parameter.

Example URLs

• /api/users?version=1
• /api/users?version=2

Spring Boot Controller Example

    @RestController
    @RequestMapping("/api/users")
    public class UserController {
    
        @GetMapping(params = "version=1")
        public String getUsersV1() {
            return "Users from API Version 1";
        }
    
        @GetMapping(params = "version=2")
        public String getUsersV2() {
            return "Users from API Version 2";
        }
    }
    

Pros

• URL remains the same
• Easy to implement

Cons

• Versioning logic is less visible
• Query parameters are usually meant for filtering, not versioning

3. Header-Based Versioning

Here, the API version is sent using a custom HTTP header.

Example Headers

• X-API-VERSION: 1
• X-API-VERSION: 2

Spring Boot Controller Example

    @RestController
    @RequestMapping("/api/users")
    public class UserController {
    
        @GetMapping(headers = "X-API-VERSION=1")
        public String getUsersV1() {
            return "Users from API Version 1";
        }
    
        @GetMapping(headers = "X-API-VERSION=2")
        public String getUsersV2() {
            return "Users from API Version 2";
        }
    }
    

Pros

• Clean URLs
• Better separation of concerns

Cons

• Not easily visible to consumers
• Harder to test via browser

4. Content Negotiation (Media Type Versioning)

This is the most RESTful approach. The version is included in the Accept header using media types.

Example Accept Headers

• Accept: application/vnd.company.app-v1+json
• Accept: application/vnd.company.app-v2+json

Spring Boot Controller Example

    @RestController
    @RequestMapping("/api/users")
    public class UserController {
    
        @GetMapping(produces = "application/vnd.company.app-v1+json")
        public String getUsersV1() {
            return "Users from API Version 1";
        }
    
        @GetMapping(produces = "application/vnd.company.app-v2+json")
        public String getUsersV2() {
            return "Users from API Version 2";
        }
    }
    

Pros

• Highly REST-compliant
• Clean and stable URLs
• Best for large enterprise APIs

Cons

• Complex to implement and understand
• Harder for beginners and manual testing

Best Practices for API Versioning

• Version only when breaking changes are introduced
• Do not version for minor bug fixes
• Deprecate old versions gradually
• Document version changes clearly
• Prefer URI or Header versioning for simplicity

Which Versioning Strategy Should You Choose?

Conclusion

Spring Boot REST API versioning is essential for building scalable and maintainable applications. Choosing the right strategy depends on your use case, client expectations, and long-term maintenance plans. For most applications, URI or Header-based versioning offers the best balance between simplicity and flexibility.