Asp.Net Core 3.0 Web API Versioning best practices

In this tutorial, we are going to cover Asp Net Core 3.0 Web API Versioning best practices using Visual Studio 2019. We will see different ways to implement API versioning in Asp.Net Core 3.0 application like URL based versioning, Query string based versioning, and then header based versioning. In one of the previous tutorials, we have discussed how to create web API in Asp.Net Core 3.0 application and then we have also discussed Asp Net Core 3.0 Web API token based authentication using JWT in visual studio 2019. So, let’s see how to implement API Versioning in Asp.Net Core 3.0 web API application.

What will you learn in this tutorial?

We will learn lots of concepts in this tutorial using simple example.

• How to create web API in Asp.Net Core 3.0 application?
• How to install versioning package? E.g. Microsoft.AspNetCore.Mvc.Versioning
• How to implement URL Based Versioning?
• How to implement Query string based versioning?
• How to implement Http header based versioning?
• How to test Http header based versioning in postman?
• How to deprecate the specfic API version?
• How to remove the version from the specific API?

Prerequisite of this tutorial:

• .NET Core 3.0
• Visual Studio 2019

ASP.NET Core 3.0 RESTful web api versioning best practices

Let’s see how to implement API versioning in Asp.Net Core 3.0 Web API application using simple example in visual studio 2019.

Step # 1: Create a Web API

In this step, we will see how to create a web api in Asp Net Core 3.0 application using visual studio 2019. So, open visual studio 2019 => then click on the “Create a new project” button => and then choose “ASP.NET Core Web Application” => and then click on the “Next” button => and then enter the project name and then choose location and then click on the “Create” button. 

Now, choose “Asp.Net Core 3.0” from the drop-down and then choose “API” template from the template pane and then click on the “Create” button. 

Then it will create a new Asp.Net Core 3.0 web API project as you do see below in the screenshot.

Now, we will add a new API in our project. So, right click on the Controllers folder and then click on add and then click on the New Item and then choose API Controller Class from the middle pane and then enter the name in the Name field and then click on the Add button. It will add a new API Controller class in your project. 

READ  Routing in ASP.NET Core 2.0 Application

Step # 2: Install Microsoft Versioning Package

Now, in this step, we will add Microsoft Versioning package (E.g. Microsoft.AspNetCore.Mvc.Versioning). So, go to NuGet Package Manager and then browse “Microsoft.AspNetCore.Mvc.Versioning” and then click on the Install button.

It will take some time, and then it will be installed within your project as you do see below in the screenshot.

Step # 3: Implement API Versioning in Asp Net Core 3.0 application using Visual Studio 2019.

Now, in this step we will cover all the ways to implement API versioning in Asp.Net Core 3.0 application using visual studio 2019. So, let’s start step by step.

Add Service in the ConfigureServices method

First-of-all, we need to add API versioning service within our ConfiugreService method in the Startup class. So, go to Startup.cs class and then add some code within the ConfigureService method as you do see below in the file.

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

view rawAPI Versioning Service in ConfigureService Method hosted with ❤ by GitHub

Let’s understand the above code.

Line # 6: This line of code is used to add the API versions in the response header.

Line # 7: This line of code is used to set the default version when the client request has not specified any version. Suppose, if we do not add this line of code and the client request has not specified any version, then the “UnsupportedApiVersion” exception will occur. So, to avoid such exceptions, we should add this line of code.

Line # 8: This line of code is used to set the default version count.

URL Based Versioning:

Now, in this point, we will see how to implement URL Based Versioning in Asp Net Core 3.0 application. So, go to your API Controller and then write two APIs as you do see below in the API class.

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using System.Threading.Tasks;
	using Microsoft.AspNetCore.Mvc;
	namespace AspNetCoreVersioning.Controllers
	{
	[ApiVersion("1.0")]
	[Route("api/v{v:apiVersion}/Values")]
	[ApiController]
	public class ValuesV1Controller : ControllerBase
	{
	// GET: api/<controller>
	[HttpGet]
	public IEnumerable<string> Get()
	{
	return new string[] { "value one from api version", "One"};
	}
	}
	[ApiVersion("2.0")]
	[Route("api/v{v:apiVersion}/Values")]
	[ApiController]
	public class ValuesV2Controller : ControllerBase
	{
	// GET: api/<controller>
	[HttpGet]
	public IEnumerable<string> Get()
	{
	return new string[] { "value two from the api version", "two" };
	}
	}
	}

view rawURL Based Versioning hosted with ❤ by GitHub

Let’s understand the above code.

READ  Role Based Authorization in Asp.Net Core 3.0

There are two API Controller Classes (ValuesV1Controll & ValuesV2Controller) in this above file. One is starting from Line # 9 and ending it on Line # 20  and the second one is starting from Line # 22 and ending it on Line # 33. 

Line # 9: In this line, we are specifying the version of API.

Line # 10: This line of code is used to specify the versioning as URL Based Versioning.

Now, run this project by pressing f5 and then enter the URL for version one API and then you will see the output as you do see below in the screenshot.

URL for Version one API: https://localhost:44358/api/v1.0/values

URL for Version one API: https://localhost:44358/api/v2.0/values

Now, enter the URL for Version two API and then you will see the output as you do see below in the screenshot.

Query String Based Versioning

Now, in this point, we will see how to implement Query String Based Versioning in Asp Net Core 3.0 application. So, go to your API Controller and then write some code as you do see below in the API class.

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using System.Threading.Tasks;
	using Microsoft.AspNetCore.Mvc;
	namespace AspNetCoreVersioning.Controllers
	{
	[ApiVersion("1.0")]
	[Route("api/Values")]
	[ApiController]
	public class ValuesV1Controller : ControllerBase
	{
	// GET: api/<controller>
	[HttpGet]
	public IEnumerable<string> Get()
	{
	return new string[] { "value one from api version", "One"};
	}
	}
	[ApiVersion("2.0")]
	[Route("api/Values")]
	[ApiController]
	public class ValuesV2Controller : ControllerBase
	{
	// GET: api/<controller>
	[HttpGet]
	public IEnumerable<string> Get()
	{
	return new string[] { "value two from the api version", "two" };
	}
	}
	}

view rawQuery Based Versioning hosted with ❤ by GitHub

Let’s understand the above code.

Line # 10: This line of code is used to specify the versioning as Query String Based Versioning.

Now, run this project by pressing f5 and then enter the URL for version one API and then you will see the output as you do see below in the screenshot.

URL for Version one API: https://localhost:44358/api/values?api-version=1.0

URL for Version Two API: https://localhost:44358/api/values?api-version=2.0

Now, enter the URL for Version two API and then you will see the output as you do see below in the screenshot.

READ  How to add Facebook login to Asp.Net Core 3.0 app using VS2019

Http Header based versioning:

Now, in this point we will see how to implement HTTP header based versioning in Asp.Net Core 3.0 application. And then we will see how to test it with postman. So, go to startup class and then configure service method and then write this below line of code as you do see below in the file.

o.ApiVersionReader = new HeaderApiVersionReader(“x-api-version”);

	public void ConfigureServices(IServiceCollection services)
	{
	services.AddControllers();
	services.AddApiVersioning(o => {
	o.ReportApiVersions = true;
	o.AssumeDefaultVersionWhenUnspecified = true;
	o.DefaultApiVersion = new ApiVersion(1, 0);
	o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
	});
	}

view rawhttp based web api versioning hosted with ❤ by GitHub

Line # 9: this line of code is used to implement HTTP header based API versioning.

Test Http Header based versioning using Postman:

Now, go to postman and then enter the URL for version one API and then set the header value and then click on the Send button. Then you will see the output as you do see below in the screenshot.

Now, set the header for version two API and then click on the Send button. Then you will see the output as you do see below in the screenshot.

How to deprecate the specfic API version?

Now, in this step we will see how to deprecate the specific API version. Sometime we  So, go to API Controller and then just set the Deprecated tag as you do see Line # 9 in the below code file.

	[ApiVersion("1.0", Deprecated = true)]
	[Route("api/Values")]
	[ApiController]
	public class ValuesV1Controller : ControllerBase
	{
	// GET: api/<controller>
	[HttpGet]
	public IEnumerable<string> Get()
	{
	return new string[] { "value one from api version", "One"};
	}
	}

view rawDeprecated Tag API Versioning hosted with ❤ by GitHub

How to remove the version from the specific API?

In some cases, we need to remove the version from the specific APIs. In these cases we will add the attribute as you do see line # 1 in the below code file.

	[ApiVersionNeutral]
	[Route("api/Values")]
	[ApiController]
	public class ValuesV1Controller : ControllerBase
	{
	// GET: api/<controller>
	[HttpGet]
	public IEnumerable<string> Get()
	{
	return new string[] { "value one from api version", "One"};
	}
	}

view rawgistfile1.txt hosted with ❤ by GitHub

Thank you for reading. Please keep visiting and sharing this blog within your community.