Since an API is a form of contract between you and your API consumers, it should be stable, consistent, well documented, and properly managed. Ideally, developers aren’t allowed to break this contract. However, this is not usually the case considering there are several instances when they are required to make a breaking change. When this happens, you need to ensure that you have put in place measures that guarantee that the change doesn’t affect your API consumers.
Versioning is the practice of creating collaborative data sharing and editing controls to ensure that your product continues to give consumers more choices without having to upgrade to the latest version. Versioning is an integral part of the API design. It arms developers with the ability to enhance their API without disintegrating the client’s applications when new versions are developed. Versioning permits clients to keep on using an existing REST API and only migrate or update their applications to the recently rolled out API versions when they are ready.
When to API Version
Although when you version highly depends on your API consumers’ expectations, it is imperative to up-version your APIs when making a breaking change. Breaking changes may occur when:
- You are renaming fields or resource paths. It is usually done to clarify something after your API is released.
- When you want to change payload structures to incorporate things like; changing an integral to afloat.
- Removing parts of the API endpoints either to fix poor choices of HTTP verbs, inconsistent design, or response codes.
Therefore, when a developer releases an API, they need to manage and monitor it all through. If one of the items mentioned above manifests, it may be an excellent time to version your API to avoid breaking the apps of your existing API consumers.
There also non-breaking changes such as adding new response parameters or new endpoints. And while these do not call for a shift in the major version number, you must track the minor versions of APIs when changes are made. This will help you to support customers that might be receiving cached versions of data or facing other daunting API issues.
Types of API Versioning
The greatest challenge to exposing services is how to handle updates to API contract. Clients may not be ready to update their apps when the API changes, and this is where a versioning strategy becomes vitally essential. Different companies can version their API’s using distinct approaches, but these are the four common ways to version an API.
1. URI Versioning
This is the most natural and most commonly used approach. It involves the inclusion of the version number in the URL path.
https://www.example.com/api/1/products
This strategy uses URI routing to pinpoint a particular version of the API. And since the version alters the URIs, clients can cache resources, such that when there is an update, it will be perceived as a new entry in the cache. This approach is straightforward, but it violates the principle that states that a URI should refer to a unique resource.
2. Query Parameter Versioning
This approach involves including the version number as one of the query parameters.
https://www.example.com/api/products?version=1
This versioning strategy is also straightforward when viewed from an implementation point of view. This approach makes it easier to switch to the newest version in case a query parameter is not specified.
3. Custom Headers Versioning
This is a technique that allows developers to version APIs by including custom headers with version numbers included in them as an attribute.
curl -H “Accepts-version: V1.”
https://www.example.com/api/products
This approach differs from query and URI versioning in the sense that it doesn’t add filler content to the URI.
4. Content Negotiation Versioning
With this approach, developers can version a single resource representation instead of the entire API. This offers more granular control and creates a considerable footprint in the code-base.
For example:
Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0
This method also doesn’t need the implementation of URI routing rules, which are introduced by versioning via the URI path. However, this approach is less accessible when compared to URI-versioned APIs. Additionally, Content negotiation may permit you to maintain a clean set URL, but at some point, you will deal with the challenge of serving different versions of content.