Mastering API Versioning in SpringMVC: Best Practices and Implementation Tips

Creating an API version is like renovating a house. Just as a house needs updates and changes over time to meet the evolving needs of its residents, an API also needs to evolve to meet the changing requirements of its users. For example, if you add new rooms or modify existing ones in your house, you need to update the blueprints and plans accordingly. Similarly, if you change the fields or routing of your API, or modify payload structures, you need to create a new API version to ensure that your customers’ digital products won’t break or be disrupted.

Sometimes, adding minor updates like new endpoints or parameters may not require a whole new API version, just as repainting a room or replacing a light fixture may not require a full-scale renovation. However, keeping track of these minor revisions can help troubleshoot technical issues for customers. Ultimately, making changes to an API means evolving the API contract, just as renovating a house means updating the blueprint.

What is API Contract

The API contract is like a legal agreement between an API producer and a consumer, outlining what the consumer can expect from the API in a machine- and human-readable format. It’s similar to a contract between a landlord and a tenant, where the landlord specifies what services they will provide and what the tenant can expect in return. This agreement establishes trust and accountability between the API producer and the consumer, allowing developers to confidently build tools using that API.

Just as a landlord may need to update the services they provide over time, an API may also need to evolve and change. For example, if a social media platform introduces a new feature allowing users to share videos, they may need to modify the API contract to include information about the new media type. However, not all aspects of the API need to be included in the contract. For instance, according to Roy Fielding, the creator of REST architecture, URIs should not be covered by the API contract as they are not part of the API itself.

Changes to the API contract can be managed through API versioning. Just as a landlord may need to update a lease agreement, an API producer may need to release a new version of the API to incorporate changes to the contract. This allows existing users to transition to the new version gradually while also providing a way to sunset outdated features and endpoints.

Overall, the API contract is a critical component of API design, ensuring that developers can confidently build tools using the API and facilitating communication and trust between the API producer and the consumer.

How to Do it in SpringMVC

There are several ways to do API versioning in a Spring MVC application. Here are some common approaches:

1. URL Versioning: In this approach, the version is specified in the URL itself, such as /v1/products or /v2/products. This is one of the simplest approaches to versioning, but it can make the URLs long and complex over time. This is not recommended approach because it violates the principle of keeping URIs (Uniform Resource Identifiers) stable over time. If the URI changes with each API version, clients would need to update their requests every time the API is updated, which can be burdensome.

Example Controllers implementation in Spring MVC

2. Request Parameter Versioning: In this approach, the version is specified as a query parameter in the URL, such as /products?version=1. This approach allows for cleaner URLs, but can make caching and testing more difficult. This approach makes it easy to make the latest API version as the default unless another version is specified. There are some issue with this approach like URL pollution, Confusing documentation and security constraints.

3. Header Versioning: In this approach, the version is specified as a custom header in the HTTP request, such as

Accept: version=1.0

This approach can be useful for APIs that require more granular versioning or want to maintain cleaner URLs.

4. Media Type Versioning: In this approach, the version is specified as a custom media type in the HTTP Accept header, such as application/vnd.company.product-v1+json. This approach can be useful for APIs that require versioning at the level of individual resources or media types.

5. Payload Versioning: In this approach, the version is specified as a property in the payload of the HTTP request or response. This approach can be useful for APIs that require versioning at the level of individual resources or properties.

In addition to these approaches, there are also several third-party libraries and frameworks that can help with API versioning in Spring MVC, such as Spring HATEOAS, Spring Cloud Gateway, and Spring Data REST. Choosing the right approach depends on the specific requirements of your API and the needs of your users.

How to inform consumer of new API version

Furthermore, when an API version becomes obsolete or is no longer supported, API clients that attempt to access it should be directed to use the latest previous API version. Any attempts to access obsolete URIs, such as those listed below, should result in one of the 30x HTTP status codes that indicate redirection, along with a Location HTTP header that directs the client to the appropriate version of the resource URI, which remains as follows:

http://knowledgecafe.dev/api/customers/1234

For API versioning scenarios, there are at least two redirection HTTP status codes that are suitable.

1. The first is 301 Moved Permanently, which indicates that the resource associated with a requested URI has been permanently moved to another URI. This new URI should be a resource instance permalink that does not contain API version information. This status code can be used to notify API clients that an obsolete or unsupported API version has been replaced by a resource permalink.
2. The second is 302 Found, which indicates that the requested resource is temporarily located at another location while the requested URI may still be supported. This status code may be useful when the version-less URIs are temporarily unavailable and a request should be repeated using the redirection address (i.e., pointing to the URI with API version embedded). This way, we can inform clients to keep using the permalink.

When Not To Version an API

1. When the API is not publicly available: If the API is for internal use only and not available to external clients, versioning may not be necessary as the API clients can be updated along with the API changes.
2. When the changes are backward-compatible: Backward-compatible changes are those that do not break existing client implementations. In such cases, versioning may not be necessary as the API can continue to support both the old and new client implementations without versioning.
3. When the API is new: If the API is new and has not yet been released, versioning may not be necessary as the API can be designed and released with a version from the start.
4. When the API has a short lifespan: If the API has a short lifespan or is intended for a specific project, versioning may not be necessary as it can be designed and released without versioning.

Summary

API versioning is an important practice that allows developers to make changes to an API without disrupting existing clients. There are different approaches to API versioning, including URL versioning, header versioning, request parameter versioning, and media type versioning. Each approach has its own pros and cons, and the choice depends on the specific use case. However, header versioning is the most commonly recommended approach as it provides better separation of concerns and is less likely to cause conflicts with other API features.

Bonus

If you want to dive deeper into Spring interview questions and learn more about tricky topics, check out my free Spring Interview Questions eBook. Click on the link to download your copy and get more insights on mastering your next Spring interview. Happy coding!