Rest API versioning

Change is inevitable and this is no different with APIs. If APIs are successful, they evolve over time. New requirements may drive you to make changes to your APIs. Advancements in technology are also a contributor to changes to APIs. Handling these changes in a way to minimize the impact on the clients is the art of versioning.

Versioning is a process of assigning unique version numbers to identify the current changes associated with the product/software. Within a given version number (major, minor), these numbers are assigned in increasing order and correspond to new developments in the software release. Hardware product or a software product, everything is versioned. Without versioning it would be a maintenance nightmare. This is a generic concept of versioning a software product.

Versioning REST API is almost similar but it has 2 parts to it.

1. The REST API contract.
2. The REST API implementation.

REST API implementation can have a different version from its API contract as the implementation can be changed for any reason like performance improvements or underlying service implementation. A new API version should be created only when there is a backwards-incompatible platform change that is being used by the client. In short, new version should be introduced for breaking changes only.

The need to version APIs #

An API defines a contract between the API and the API client. Some changes, such as minor bug fixes, may not require any alteration to the API contract. However, a change in the structure of the resource or response, may require a change in the API contract. Changes may or may not be backward compatible. If the change is backward compatible, it may be possible to handle it within the same API version. Changes that are not backward compatible require a new version of the API to be introduced. Versioning APIs helps maintain compatibility, enabling debugging and dependency control.

How to version APIs #

There are several ways to version an API and it depends on the internal practice of an organization. One way is to have a version format which looks like the following:

MAJOR.MINOR.PATCH

Major version: This version is changed only if the change is a breaking change which is not backward compatible. This version is used to identify the API being consumed either in the URI or header.
    
Minor versions: This version is changed if there is are additional features implemented.
    
Patch versions: This version is incremented for any bug fixes.

If major version is incremented, then minor and patch version starts from 0 and if minor version is incremented patch version starts from 0.

For example,

	
Current API version: 3.2.6

patch change: 3.2.7
Minor change: 3.3.0
Major change: 4.0.0

All changes irrespective of major, minor or patch should be communicated in change logs to inform API consumers.

API version management #

There are multiple ways to version an API.

• Versioning via URLs.
• Versioning via HTTP Header.
• Versioning via Query Parameters.

Versioning via URLs:

API versioning via URL is the most common method. It also makes easy as the URL will also identify the exact version of the API being consumed. URL versioning is not RESTful compliant as URIs should represent resources and not versions. Example,

api.programmerspub.com/v1/customers

In this example, V1 is the API version and it is the MAJOR version. Minor and patch version number are not included in the API URL as the minor and patch changes will be part of the major versioning.

Versioning via HTTP Header:

Another way to implement versioning in API is via HTTP headers and its more RESTFul. The advantage of this approach is that the URI is cleaner as it keep the API version out it. And resource level versioning can be done which preserves URIs between resources.

The use of an HTTP ‘Accept’ header is one of the preferred choice. FOr example

Accept: application/vnd.programmerspub[.version].param[+json] Accept: application/vnd.myapi.v2+json

Versioning via Query Parameters

This is yet another common approach to versioning API. In this approach the client specifies the version number as a query parameter in the request, as follows: api.programmerspub.com/customers?version=v1

This approach works well when the resource representation is versioned. In such cases, it is necessary to also put in transformation logic to transform the resource representation based on the version specified.

Conclusion #

Versioning is a crucial part of API design so never release an API without a version. I have mentioned this few times in my previous posts “The best designed API has only one version”. But is this possible? especially in today’s world where technology evolves overnight.

What are your views on versioning a REST API, let me know your views in comments.