What are the best practices for versioning REST APIs in a Spring Boot application?

Question

Accepted Answer

REST API versioning is a strategy used to manage changes in APIs without breaking existing client applications. It allows multiple versions of an API to coexist so that older clients continue to work while new features are introduced in newer versions.

Key Points:
• API versioning ensures backward compatibility for existing consumers.
• Proper versioning simplifies API evolution and maintenance.
• URL versioning is the most commonly used and easiest approach to manage.

Example:
Suppose an application initially exposes:

GET /api/v1/products

Later, a new response structure is introduced with additional fields:

GET /api/v2/products

Existing applications continue using v1 while newer clients migrate to v2 without disruption.

Common Versioning Strategies:

1. URL Versioning

Example:

/api/v1/orders
/api/v2/orders

Advantages:
• Easy to understand and implement.
• Clearly visible in API documentation.
• Widely adopted in enterprise applications.

2. Header Versioning

Example:

GET /orders
API-VERSION: 2

Advantages:
• Keeps URLs clean.
• Useful when URL changes are undesirable.

3. Media Type Versioning

Example:

Accept:
application/vnd.company.v1+json

Accept:
application/vnd.company.v2+json

Advantages:
• Supports content negotiation.
• Suitable for mature public APIs.

4. Request Parameter Versioning

Example:

/orders?version=1
/orders?version=2

Advantages:
• Easy to implement.
• Useful for internal APIs.

Disadvantages:
• Less commonly used in enterprise applications.

Spring Boot Example:

```
@GetMapping("/api/v1/products")
public List getProductsV1() {
    return service.getProducts();
}

@GetMapping("/api/v2/products")
public List getProductsV2() {
    return service.getProductsV2();
}
```
Best Practices:

• Prefer URL versioning for public REST APIs.
• Introduce new versions only for breaking changes.
• Maintain backward compatibility whenever possible.
• Deprecate old versions gradually with proper communication.
• Document all API versions clearly using Swagger or OpenAPI.

When to Create a New Version:

• Response structure changes.
• Request contract changes.
• Authentication mechanism changes.
• Existing functionality is removed or modified.

Avoid creating a new version for:
• Bug fixes.
• Performance improvements.
• Internal implementation changes.

Real-World Example:

E-commerce API:

Version 1:
• Basic product details.

Version 2:
• Product details with inventory and ratings.

Version 3:
• Product recommendations and AI search support.

Older mobile applications continue using older versions while new applications adopt newer APIs.

Recommended Approach:

For most Spring Boot applications:

/api/v1/resource
/api/v2/resource

This approach provides simplicity, clarity, and easier maintenance.

Interview Tip:
A concise interview answer is: REST API versioning allows applications to evolve without breaking existing clients. Spring Boot supports multiple strategies such as URL versioning, header versioning, media type versioning, and request parameter versioning. In most enterprise applications, URL versioning using endpoints like /api/v1/products and /api/v2/products is preferred because it is simple, explicit, and easy to maintain.