API Versioning In ASP.NET Core With Three Different Ways

Introduction

Versioning is very important for all the web API applications which are being consumed by people for long time. For instance, our API application is being used by public for a long time and we want to make some drastic changes in the application which will affect the entire flow of the application. Obviously, the changes will affect the previous consumers also. To overcome this situation, end users also should make the changes in their application accordingly. This is not a genuine practice, right? Instead of changing the existing API application, we can create a new version of the API and give to public. It will not affect the former consumers. There are three ways to create versioning in API applications. We can see one by one.

Approach1: Versioning with URL Routes

We can pass the API version through URL routes and produce different versions of API controllers and methods.

We must install “Microsoft.AspNetCore.Mvc.Versioning” library using NuGet package manger.

We can add below entries inside the “ConfigureServices” method in Startup class.

public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddApiVersioning(options =>
{
options.ReportApiVersions = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
});
}

We can create a new controller with default methods using scaffolding template.

I have removed all other methods except GET method. I have also added version route attribute for the controller. I have created another controller class with GET method inside the same file. Now, we have two controllers with same GET method. But it will return different results. We can check the result using Postman tool.

ValuesController.cs

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
namespace URLVersioning.Controllers
{
[ApiVersion("1.0")]
[Route("v{v:apiVersion}/values")]
[ApiController]
public class Values1Controller : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1 - V1", "value2 - V1" };
}
}
[ApiVersion("2.0")]
[Route("v{v:apiVersion}/values")]
[ApiController]
public class Values2Controller : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1 - V2", "value2 - V2" };
}
}
}

We can enter the URL with version 1.0. This will give following result.

We can check with version 2.0 and you will get below result.

If you look at the response header, you can see the supported API versions. Currently, we have only two versions. We can add as many as we want.

In this approach, the existing consumers of the API should change endpoints to accommodate new changes. Because, we have changed the URL routes. This is a major drawback of this approach. To overcome this disadvantage, we have two more approaches available.

Approach2: Versioning with HTTP Header

In this approach, we will pass the version along with HTTP header instead of passing it as URL. We must add one more option entry for Http Header in Startup class.

public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddApiVersioning(options => {
options.ReportApiVersions = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ApiVersionReader =
new HeaderApiVersionReader("X-API-Version");
});
}

We have added a new Http Header entry “X-API-Version". We can modify the existing routes of controller class. We don’t need the version in route anymore.

ValuesController.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
namespace HttpHeaderVersioning.Controllers
{
[ApiVersion("1.0")]
[Route("values")]
[ApiController]
public class Values1Controller : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1 - V1", "value2 - V1" };
}
}
[ApiVersion("2.0")]
[Route("values")]
[ApiController]
public class Values2Controller : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1 - V2", "value2 - V2" };
}
}
}

We can pass the version as Http Header through Postman and see the result.

If you are not passing any version as header, it will consider default version as per Startup entry and give the corresponding result. In our case, we have given 1.0 as default version.

Approach3 : Versioning with Query parameter

We can achieve the API versioning through query parameter also. For that, we must remove the previous Startup entry for Http Header.

No need to change the controller file. We can run the application and check the request in Postman using query param.

We should pass the query param as “api-version”. If you execute the request without any query param, you will get value from the controller with default version. In our case 1.0 is the default version.

Conclusion

In this post, we have seen three different types of versioning for ASP.NET Core Web API application. First, we have used URL routing versioning and then we have seen the versioning through Http Headers. Finally, we have seen the third option with query param. Both http header and query param methods do not affect the existing consumers of Web API. But if you choose the URL routing method, you must change all the existing endpoints of API.

7 Comments

Join the conversation! Your thoughts help the community grow.

Jay Krishna Reddy6y ago
Nice article
Ano Mepani6y ago
Let's say if you have to introduce API versioning to existing system which already has 100s of API and it is already used by Multiple user,, How can we do it with minimal efforts any suggestion?
- Sarathlal Saseendran6y ago
  Hi Ano Mepani, in that case you can use either http header or query param
Sundaram Subramanian6y ago
Good note. Thanks Sarath
- Sarathlal Saseendran6y ago
  Thank you very much Sundaram Subramanian
Praveen Nair6y ago
Very informative.
- Sarathlal Saseendran6y ago
  Thanks Praveen ji.