Introduction
This is the structure of this article,
- Introduction
- A - What is Web API Versioning
- B - When to Versioning
- C - Why Versioning APIs
- D - How to Versioning
- Path-based versioning
- Header-based versioning
- Query string-based versioning
A - What is Versioning
API is a form of contract between you and your API consumers, it should be stable, consistent, well documented, and properly managed.
Versions allow you to present groups of related APIs to your developers. You can use versions to handle breaking changes in your API safely. Clients can choose to use your new API version when they're ready, while existing clients continue to use an older version.
B - When to Versioning
APIs only need to be up-versioned when a breaking change is made.
Breaking changes include:
- a change in the format of the response data for one or more calls
- a change in the request or response type (i.e. changing an integer to a float)
- removing any part of the API.
C - Why Versioning APIs
For most purposes, each API version can be considered its own independent API. Two different API versions might have different sets of operations and different policies.
With versions you can:
- Publish multiple versions of your API at the same time.
- Use a path, query string, or header to differentiate between versions.
- Use any string value you wish to identify your version, which could be a number, a date, or a name.
- Show your API versions grouped together on the developer portal.
- Take an existing (non-versioned) API, and create a new version of it without breaking existing clients.
D - How to Versioning APIs
Different API developers have different requirements for versioning. This is the popular ways to make the versioning:
Path-based versioning
When the path versioning scheme is used, the version identifier needs to be included in the URL path for any API requests.
For example
https://apis.contoso.com/products/v1 and https://apis.contoso.com/products/v2
could refer to the same products API but to versions v1 and v2 respectively.
The format of an API request URL when using path-based versioning is:
https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.
Header-based versioning
When the header versioning scheme is used, the version identifier needs to be included in an HTTP request header for any API requests. You can specify the name of the HTTP request header.
For example, you might create a custom header named Api-Version, and clients could specify v1 or v2 in the value of this header.
Query string-based versioning
When the query string versioning scheme is used, the version identifier needs to be included in a query string parameter for any API requests. You can specify the name of the query string parameter.
The format of an API request URL when using query string-based versioning is:
- https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.
For example,
- https://apis.contoso.com/products?api-version=v1 and
- https://apis.contoso.com/products?api-version=v2
could refer to the same products API but to versions v1 and v2 respectively.
Reference