RESTful API versioning with ASP.NET Core
This blog post will discuss about the commonly used API Versioning strategies and how to implement them in ASP.NET Core Web API.
For the demo purposes I am creating an ASP.NET Core WEB API project using
dotnet new webapi command. To implement versioning we need to add reference of the
Microsoft.AspNetCore.Mvc.Versioning nuget package, which we can do by running ` dotnet add package Microsoft.AspNetCore.Mvc.Versioning` command.
Once the package reference is added, in the
ConfigureServices method, Versioning support can be added using
AddApiVersioning(); method, like this.
Now if you try to access the
https://localhost:5001/weatherforecast endpoint, you will get a Bad Request Error with a response like this.
So we need to include the version in the request. But we also need to keep one version as default one, so that it always returns response if no version specified. To implement this, we can add some code like this in the
We have modified the configuration to use default version if no version is mentioned. It is also good, if we know which all versions our API is supported, we can configure this also in the
AddApiVersioning configuration, so while calling the API - in the response we will be able to know which all API versions are available.
Once this configuration is applied, ASP.NET Core returns a HTTP Header -
api-supported-versions in the response with the supported version values, like this.
By default ASP.NET Core creates 1.0 as the default version. If you want to configure your own instead of 1.0, you can do it like this.
In this scenario, default version will be 1.2 instead of 1.0.
Next we will explore how we can add version support in controllers and action methods.
It is common convention to use version as part of the URL. First we will explore how we can implement versioning support like this. To do this, add the
ApiVersion attribute to the controller / action method. Along with this, we need to modify the route attribute as well, so that the ASP.NET Core can route the requests.
We can access the API methods with the version attribute - https://localhost:5001/v1.0/weatherforecast. We can apply the a different version like this.
You can map action methods to specific API versions using
MapToApiVersion attribute, like this.
GetV2 method, API response contains 10 items instead of 5. You can invoke this method like this - https://localhost:5001/v2.0/weatherforecast
Next we will explore how to invoke the API endpoints with version information as query strings. To configure the API Versioning to use query strings as a versioning strategy using a Version Reader. We can configure the
ApiVersionReader property to use
QueryStringApiVersionReader class, so that we can provide the API version as query string.
We can invoke the API endpoint with the version as query string - https://localhost:5001/weatherforecast?api-version=1.0
Another versioning scenario is including the version information in the Http request header. Similar to
QueryStringApiVersionReader ASP.NET Core provides a
HeaderApiVersionReader, if this
ApiVersionReader property is configured, we need to provide the version information along with request headers.
We can even configure ASP.NET Core versioning to read version information from
Media Type or
Accept header as well. So we need to provide the version along with Accept header. Also we can configure it support multiple schemes together.
There might be a scenario, where you might want to deprecate some versions. You can do this with
Deprecated property in
ApiVersion version attribute. The client could read the
api-deprecated-versions http header and know about the deprecated APIs.
Here is the response details from Web API.
In this post we will explored about versioning ASP.NET Core WEB API endpoints, different versioning strategies and how to deprecate a specific endpoint version etc. Next post we will explore how to enable swagger support for Web API with versions.
Happy Programming :)