Version - NeoSOFT-Technologies/application-gateway Wiki

While working on an existing application or creating a new one, we may create multiple APIs that may be consumed by many clients. At some point in time we eventually run into the point where a breaking change might be inevitable. Due to this, we may need to provide more functionality in the existing APIs. However, existing API can be consumed by many clients so instead of replacing the existing API we would provide a new version of our API so that consumers of the former model would be still served.

API versioning is the process of iterating different versions of your API. Ultimately a part of API design, API versioning often accommodates API consumption changes, structural API shifts, and modifications to the underlying software or program which the API has been built upon.

Why is API versioning required?

API versioning is required because it ensures stability and reliability. If you don't properly version APIs, it can have disastrous effects on downstream products and services.

Acceptance criteria to be added

Navigate and Create API

In update API page, there is one section for versioning named Version.

Version1

This page contains two sections named Version Setting and Versions as shown below,

Version2

Version3

In Version Setting section, we can choose Version Data Location for version type and we need to add Version Identifier Key Name.

Version4

In Versions section, we can add versions with Override Target Host and Expire Date.

Version5

API Versioning Ways

It can be done by using the following methods:

Header

Custom Headers are used for providing additional information, troubleshooting and implementing server-side logic, etc. We will send the version information in the custom header and check its value and return the response according to its value.

Add version information in request header using the postman in order to test the API Versioning as shown below,

For version v1,

VersionHeaderTest1

For version v2,

VersionHeaderTest2

URL or Form parameter

In this type, it allows you to pass the version of the API as a parameter in the URL. Here is how the URL may look like.

Run the API using the postman in order to test the API Versioning as shown below,

For version v1,

VersionURLTest1

For version v2,

VersionURLTest2

First Part of Path

Using the URL path is the most straightforward approach and most commonly used as well. It gives a clean separation between different versions. Versions are explicitly mentioned in the URL of the API endpoints. Here is how it would look like.

Run the API using the postman in order to test the API Versioning as shown below,

For version v1,

VersionPathTest1

For version v2,

VersionPathTest2