REST API versioning

Because of some changes we are making, APIs need to be up-versioned.

1. Changes in the format of the response data.
2. Changes in the request or response type.
3. Removing any part of the API.

Clients who may be experiencing other API issues or maybe receiving cached versions of data are some reasons that we need to track the minor versions of APIs and provide support. There are no specific guidelines for REST API versioning, but we can find some common approaches that fall into 4 categories. 

1. Versioning using URI Path.
2. Versioning using query parameters.
3. Versioning using custom headers.
4. Versioning using content negotiation.

Versioning using URI Path.

To version a REST API, we can put the version number in the URI path. It is like 1.2.3. format. This means ‘Major.Minor.Patch’. In the major update, we can create a new API and the version number is used to route to the correct host. In minor and patch versions, developers can communicate in changelogs whether it is new functionality or a bug fix. Normally those are ‘backward-compatible’ updates.

Ex: https://www.testapi.com/api/1/samples, https://www.testapi.com/api/v1/samples

This version can be a number, dates, project names, seasons, or other meaningful identifiers.

Versioning using query parameters.

Developers can include the version number as a query parameter. Query parameters are more difficult to use for routing requests to the proper API version.

Ex: https://www.testapi.com/api/samples?version=1, https://www.testapi.com/api/samples?version=1.2.3

Versioning using custom headers.

Developers can provide custom headers with the version number as an attribute. The main difference with this is, this does not change the URI. This requires custom headers.

Ex: curl -H “Accepts-version: 1.2.3” https://www.testapi.com/api/samples

Best Practices

Read More: