API Versioning in .NET 6.0

When it comes to deploying an API for your .NET Core project, there has to be a checklist of the features that are necessary for this process. One such feature that tops this list is to implement API versioning in ASP.NET Core. It is a very essential approach to anticipate all the changes that may be essential after the API is published and clients start using it. This means that once the API is published to a production server, the ASP.NET core development team has to be very careful with any future changes they make. The reason behind it is that the new changes made by the developer must not break the existing client applications that are using the API. And this is why the concept of API versioning came into the picture. The versioning semantics stated in the Microsoft REST Guidelines are followed by the default API versioning configuration.

API versioning in ASP.NET core is an approach that enables different clients to get distinct implementations of the same controller base when a request is sent or a URL path is entered. So, creating an API that has multiple versions that can behave differently is essential. By following this approach, the client requirement may change with time but there is no compromise seen when it comes to the availability and integrity of the data for the existing client apps.

Methods of ASP.NET Core API Versioning & Routing

1. Setup

Start with the Installation of the Versioning Nuget package from Nuget Package Manager or Package Manager Console in the API project as shown below

Microsoft.AspNetCore.Mvc.Versioning

Write the following code in Startup.cs in the ConfigureService method.

services.AddApiVersioning(config => { config.DefaultApiVersion = new ApiVersion(1, 0); config.AssumeDefaultVersionWhenUnspecified = true; config.ReportApiVersions = true; config.ApiVersionReader = new HeaderApiVersionReader("api-version"); });

AssumeDefaultVersionWhenUnspecified -When the API version of the current application is not specified in the request then set the value as true to get the default API version number.

ReportApiVersions – If you set the value of ReportApiVersion as true, then the information of the version is generated and displayed in the header section as shown in the image below.

There are mainly three different methods/techniques in Asp.NET core technology used by asp.net core development company for developing Web API Applications.

2. Versioning with URL Routing

In Controller add API method add as below for version 1.0

[HttpGet] [Route("[controller]", Order = 1)] [Route("api/v{version:apiVersion}/[controller]", Order = 2)] [ApiVersion("1.0")] public IEnumerable Get() { var person = _personService.GetList(); return person; }

Call above Api with version 1.0 in postman, as given in below image and check result

In Controller add API method add as below for version 2.0

[HttpGet] [Route("[controller]", Order = 1)] [Route("api/v{version:apiVersion}/[controller]", Order = 2)] [ApiVersion("2.0")] public Person GetV1_1() { var person = _personService.GetList().FirstOrDefault(); return person; }

To call, above API with version 2.0 check the below image

Using this methodology, the existing consumers will have to change the endpoints to validate recently developed changes. Ideally, we need to change the URL routes, otherwise, it can lead to major disadvantages. To overcome this drawback, we have two other ways to achieve versioning.

3. Versioning using HTTP Header

In this method, the version needs to be passed to the HTTP Header. One more option is required in Startup.cs to add an entry in HTTP Header.

services.AddApiVersioning(config =>   { // default API Version set as 1.0 config.DefaultApiVersion = new ApiVersion(1, 0); // If the API version not defined in the request, default API version will be used. config.AssumeDefaultVersionWhenUnspecified = true; config.ReportApiVersions = true; config.ApiVersionReader = new HeaderApiVersionReader("api-version"); });

The version can be passed as Http Header through the Postman method and the results can be displayed as shown in the below image. If the version is not passed into the header, the default version set in Startup.cs will be used. Here’s the default version used is version 1.0.

4. Versioning using the Query parameter

With this approach, the users can pass API versions in the query string as displayed in the below image. To use this, users need to configure the first header version and remove all others from ConfigureService in Startup.cs.

5. Deprecating API Version

We can deprecate the API version which is no longer used. We do not need to remove the version, as it can be used somewhere. We can mark it as deprecated, so when an API is called, the header information displays that the called API is deprecated.

[HttpGet] [Route("[controller]", Order = 1)] [Route("api/v{version:apiVersion}/[controller]", Order = 2)] [ApiVersion("1.0", Deprecated = true)] public IEnumerable Get() { var person = _personService.GetList(); return person; }

The users will find the depreciated version information as shown in the image below.