Best Practice: Versioning REST API

1) When we should do the Versioning of API

Versioning (REST) API is often a last priority during development process. In fact it should be the foremost for Designing an API, which provide the ease of consumption and usability to the end users.

2) Why Versioning become Mandatory

In the following scenario,versioning become mandatory:

1) How you response the Issues/ Feedback, your API user facing/providing after release of the API?

2) How you will manage if your endpoint not needed at all?

3) How you manage if the POST method in your API, need more key?

4) How you manage if your API keeps evolving, as the business get expanded?

5) How you manage if the semantics keep changing due to business evolution?

3) How To do the Versioning

These days the three most popular ways are following:

a) URI Versioning: It also know as route versioning.

i) Endpoints: /<API-Version>/<Path>/<sub-path>/<content>

Example: /v9/sbp/live/videoconf

ii) Pros: Most popular and easy.

iii) Cons: Polluting the URI, due to increment in the length.

iv) Company who using mostly: Twitter.

b) Custom header versioning.

i) Endpoints: /<Path>/<sub-path>/<content>

Example: /sbp/live/videoconf

Accept-Version: v9

ii) Pros: Specify the version of the API, and the server can respond appropriately with the correct response data as well as parse the incoming payload on the fly.

iii) Cons: Increasing the overall latency, as each time server have to parse the header prior to send the response.

Unnecessary forcing user to send the custom header.

iv) Company who using mostly: Microsoft.

c) Query Paremeter Versioning.

i) Endpoints: /<Path>/<sub-path>/<content>/?version=versionNumber

Example: /sbp/live/videoconf/?version=v9

ii) Pros: Ease in use and more dynamic.

iii) Cons: Cache issue.

iv) Company who using mostly: Amazon.

********** The END *****************