ASP.NET Web API-Versioning

API versioning is a technique used to manage changes and updates in an API while maintaining backward compatibility for existing clients. It allows different versions of an API to coexist, enabling clients to choose which version they want to interact with.

Types of API Versioning

Respecting agreements with your current API customers is the most frequent justification for API versioning. When they set up your API, their apps may rely on how it works. They might not be prepared to change their apps in the same way just because you need to update your API.

API versioning allows for a smooth transition between releases. Since you can still use the out-of-date functionality in earlier versions, it's the best way to sunset an asset or endpoint. Your development timeline can also be noted in your API documentation, which will assist your users to stay informed and make the appropriate adjustments.

You can construct different versions of your API in a variety of ways. The following list includes some of the most prevalent API versioning.

1. URI Versioning
2. Query Parameter Versioning
3. Header Versioning
4. Media Type Versioning (Content Negotiation)
5. Custom Header Versioning
6. Subdomain Versioning
7. Mixed Versioning

1. URI Versioning

In this strategy, the version is included in the URI path.

Example

https://api.example.com/v1/products or https://api.example.com/products?api-version=1.0

2. Query Parameter Versioning

The version is specified as a query parameter in the API request.

Example

https://api.example.com/products?version=1.0

3. Header Versioning

The version is included as a custom header in the API request.

Example

GET /products
Headers: X-API-Version: 1.0

4. Media Type Versioning (Content Negotiation)

The version is indicated in the media type of the request or response.

Example

GET /products
Headers: Accept: application/vnd.example.v1+json

5. Custom Header Versioning

A custom header specifically designed for versioning is used.

Example

GET /products
Headers: X-API-Version: 1.0

6. Subdomain Versioning

The version is specified as a subdomain in the URL.

Example

https://v1.api.example.com/products

7. Mixed Versioning

A combination of different versioning strategies can be used based on the specific needs of the API.

Examples of API Versioning

Here are a few examples of APIs that use mixed versioning strategies:

1. GitHub API

GitHub's API uses a combination of URI versioning and custom media type versioning. The API version is included in the URI path, such as /repos/:owner/:repo for the latest version. However, they also support custom media types for versioning.

Example

The Accept header can be set to application/vnd.github.v3+json to specify the desired version.

2. Microsoft Graph API

Microsoft Graph API combines URI versioning and custom header versioning. The API version is included in the URI path, such as /v1.0/me/drive/root. Additionally, the Prefer header can be used to specify the version preference

such as Prefer: outlook.timezone="Pacific Standard Time".