API Versioning using ASP.net Core

  • Post category:asp.net core
  • Reading time:5 mins read

Step 1:
Open Visual Studio 2022 and Click Create New Project and choose ASP.NET Core Web API project.

Step 2:
Choose .NET 6.0 Framework or you can choose .NET 5.0 , For .NET 6.0 we will work in Program.cs file and for .NET 5.0 we will do the same thing in Startup.cs file.

Step 3:
Install NuGet Package

1. Right click on the project and and select Manage NuGet Package

2. Install the following plugins

  • Microsoft.AspNetCore.Mvc.Versioning

Step 4:
Now add the versioning service in the application. Go to the Program.cs class Add

builder.Services.AddApiVersioning();

your Program.cs class should look like this now

Step 5:
Now add a Class named Item.cs on the solution. and copy paste this code.

namespace ApiVersioning
{
  public class Itemv1
   {
     public int Id { get; set; }
     public string Name { get; set; }
   }
}

Step 6:
Now add a Controller named ItemController.cs and add the following code there and run the project.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace ApiVersioning.Controllers
{
    [Route("api/[controller]")]
    [ApiController]

    public class ItemController : ControllerBase
    {
        [HttpGet("{id}")]
        public IActionResult GetItemv1([FromRoute] int id)
        {
            var item = new Itemv1
            {
                Id = id,
                Name = "ABC"
            };
            return Ok(item);
        }
    }
}

Now Check it on Postman
URL : https://localhost:44320/api/item/1

This will return An API version is required, but was not specified. because we didn’t specify the version. Now go back to Program.cs class and add the following code.

builder.Services.AddApiVersioning(config =>
{
  config.DefaultApiVersion = ApiVersion.Default;
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
});

The error will be resolved now and all the api version is now set to a default version. By setting the ReportApiVersions = true you can able to see all the supported version of the APIs.

Step 7:
Now, Go back to Item.cs class and add this following code.

namespace ApiVersioning
{
  public class Itemv1
  { 
    public int Id { get; set; }
    public string Name { get; set; }
  }
  public class Itemv2
  {
    public int Id { get; set; }
    public string ProductName { get; set; }
  }
}

Step 8:
Now  go to ItemController.cs and add this following code.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace ApiVersioning.Controllers
{
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    [Route("api/[controller]")]
    [ApiController]
     public class ItemController : ControllerBase
     {
        [HttpGet("{id}")]
        public IActionResult GetItemv1([FromRoute] int id)
        {
            var item = new Itemv1
            {
                Id = id,
                Name = "ABC"
            };
            return Ok(item);
        }
        [HttpGet("{id}")]
        [MapToApiVersion("2.0")]

        public IActionResult GetItemv2([FromRoute] int id)
        {
            var item = new Itemv2
            {
                Id = id,
                ProductName = "XYZ"
            };
            return Ok(item);
        }
    }
}

Here you can see another method with different version is created which is mapping with [MapToApiVersion(“2.0”)] and at the top of the class we specified that two version of API is existed here by this two attributes [ApiVersion(“1.0”)] & [ApiVersion(“2.0”)]

First method will called by its default version.

Now Check

URL: https://localhost:44320/api/item/1

This returns the default API but the 2nd version of the API you need to add a version number at the end of the URL.

URL: https://localhost:44320/api/item/1?api-version=2.0

here you can clearly see this return the 2nd API where product name is XYZ.

Now tell what will this URL “https://localhost:44320/api/item/1?api-version=1.0” return ??

Step 9:
Now Change the route attribute to

[Route("api/v{version:apiVersion}/[controller]")]

and Run the application again.

Now Check

URL: https://localhost:44320/api/v1/item/1

URL: https://localhost:44320/api/v2/item/1

That’s All. Happy Versioning .

DEMO PROJECT : APIVersioning(Github)

Leave a Reply