API versioning in .net core (.net 7)

Photo by Jan Loyde Cabrera on Unsplash

When you are going to do some breaking changes in your apis, it is better to create a new version for that, so that user don’t freaked out. They still can use the older APIs and get ready for new changes. There are various way to create a versions of your APIs like

1. Query string
2. URL
3. HTTP header

If you prefer video version then you can checkout this video with same content.

YouTube versoin of this article

We are going to look into the 2nd option, Versioning with URL.

Create a new project with .net cli

dotnet new webapi -o ApiVersionDemo
code ApiVersionDemo

Now install this package

Microsoft.AspNetCore.Mvc.Versioning

Open the program.cs file and add these line.

 builder.Services.AddApiVersioning(options =>
    {
        options.DefaultApiVersion = new ApiVersion(1, 0);
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.ReportApiVersions = true;
    });

Now lets break it a bit.

DefaultApiVersion, sets the default version, if not passed.

AssumeDefaultVersionWhenUnspecified, specifies that whether or not to assume a default api version, if version not specified. I

By setting ReportApiVersions=true, this option enables sending the api-supported-versions and api-deprecated-versions HTTP header in responses.

Lets create our first Controller with name UsersController and write this code there.

using Microsoft.AspNetCore.Mvc;

namespace ApiVersioningDemo.Controllers
{
    [ApiVersion("1.0")]
    [Route("api/v{version:apiVersion}/users")]
    [ApiController]
    public class UsersController : ControllerBase
    {
        List<string> users= new List<string>{"A1","A7","A5","A4","A5","B1","B2","B5","B6","B57","B21"};
       
        [HttpGet]
        public IActionResult Get(){
            return Ok(users);
        }
    }
}

Attribut [ApiVersion(“1.0”) tells that it is a version 1 api endpoint. Now lets, test these api and in response header you will get api-supported-version information. Your endpoint will be “/api/v32/users”. I am using ThunderClient extension of vs code, to test web apis, you can use other options like postman or insomnia.

api v1

Now, lets create second version to of this API. Create a new controller UsersV2Controller.

using Microsoft.AspNetCore.Mvc;

namespace ApiVersioningDemo.Controllers
{
    [ApiVersion("2.0")]
    [Route("api/v{version:apiVersion}/users")]
    [ApiController]
    public class UsersV2Controller : ControllerBase
    {
        List<string> users= new List<string>{"A1","A7","A5","A4","A5","B1","B2","B5","B6","B57","B21"};
       
        [HttpGet]
        public IActionResult Get(){
            users= users.Where(user=>user.ToLower().StartsWith("b")).ToList();
            return Ok(users);
        }
    }
}

This controller’s get method will return the list of string, which starts with “b”. Lets check its response header. Your endpoint will be “/api/v2/users”.

api v2

Now, it is a good choice to deprecate the older version, so that consumer can prepare for newer version. In version 1 controller , replace the ApiVersion attribute with this code.

[ApiVersion("1.0",Deprecated =true)]

Your controller will look like this now.

    [ApiVersion("1.0",Deprecated =true)]
    [Route("api/v{version:apiVersion}/users")]
    [ApiController]
    public class UsersController : ControllerBase
    {
      // other stuff will be the same
    }

You can check the response header now.

So that was all about version in .net core web apis.

Connect with me
👉 Twitter: https://twitter.com/ravi_devrani
👉 GitHub: https://github.com/rd003
👉 YouTube: https://youtube.com/@ravindradevrani

Become a supporter ❤:
You can buy me a coffee 🍵 : https://www.buymeacoffee.com/ravindradevrani

Thanks a lot 🙂🙂