API Versioning in .Net 7

Photo by Glenn Carstens-Peters on Unsplash

The last time when you did a release in production, your API was fairly new in the market and had just one browser-based app development team to work with. You coordinated with the client app development team and did a synchronized release. But this time, you have got hundreds of client app development teams from various customer organizations using your API. A synchronized release is no more an option. How do you go about releasing new features and some updates in your API without disrupting the client apps? API versioning is the answer to the conundrum you’re facing.

What is API Versioning?

API versioning is the practice of managing changes to an API and ensuring that these changes are made without disrupting clients. A good API versioning strategy communicates the changes made and allows API consumers to decide when to upgrade to the latest version at their own pace.

Jamie Juviler https://blog.hubspot.com/website/api-versioning

What it entails is to run different versions of the API in parallel. That brings us to the exciting problem of routing the requests to the intended version of the API.

If an older version of API is to be discontinued in the interest of lesser maintenance efforts, then the client app developers can be notified of the timeline by which the upgrade of client apps needs to be made to use a newer version of the API.

Why is API versioning needed?

Changes in an API like any other software are inevitable. But in production, a new release of an API with breaking changes may disrupt the client apps if they are not upgraded in sync with the API. But in most cases, the team developing API and the team developing clients are separate, and may even belong to different organizations. A synchronized release may need communication back and forth between these teams, which would limit the rate with which the API team could bring out new features and could many times become overbearing for the client app development team. That’s where API versioning comes into the picture. It is required to allow the API client apps to keep working non-disruptively even after an upgrade is made to the API.

How is API versioning done?

As soon as we bring our thoughts into the realm of “how”, we start thinking of technology-specific implementations.

For this article, we would implement versioning in a .Net 7 Web API application.

Now the question comes, do we need to implement the solution of routing the requests to the intended version of API starting from scratch? Fortunately, we don’t. There’s a famous library Asp.Versioning.Mvc which we can use to make our lives easy. This NuGet library provides the features to implement API versioning specifically for .Net Core Web API applications. Other flavors of this library are available at https://github.com/dotnet/aspnet-api-versioning which provides support for other types of applications.

To follow along with the steps written below, I have made a code repository available here https://github.com/FOSSKolkata/api-versioning-demo. The repository contains folders for different milestones we achieve while applying the changes suggested in this article and my probable future articles dealing with API versioning. The initial code on top of which the below steps need to be applied is kept in the folder “Milestone 0”. You can clone the repository and start following the steps written below.

First Step

Make a copy of the content of the folder “Milestone 0”. Open the solution within. Add NuGet package Asp.Versioning.Mvc to the API project.

Second Step

Add the following code snippet to the ConfigureServices method in the Startup class.

services.AddApiVersioning(setup =>
{
    setup.ReportApiVersions = true;
}).AddMvc();

ReportApiVersions when set to true reports back all the supported and deprecated versions of API endpoints in the response headers.

Third Step

Add the ApiVersion attribute on the controller class, and pass “1.0” as the version number. This basic setup makes all the endpoints included in the controller class be versioned as “1.0”.

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

namespace ApiVersioningDemoInNet7.Controllers
{
    [ApiVersion("1.0")]
    [Route("api/[controller]")]
    [ApiController]
    public class TestController : ControllerBase
    {
        
        [HttpGet, Route("testmethod")]
        public string TestMethod()
        {
            return "Test method call successful";
        }
    }
}

Now it’s time to test the versioning setup. Run the project and type the URL: https://localhost:{port}/api/test/testmethod?api-version=1.0 (replace {port} with correct value) on the browser address bar and hit enter. And voila! The browser displays “Test method call successful”. Check the network tab in Developer Tools of the browser, the response header “Api-Supported-Versions” should have a value “1.0”.

Note that you’ve passed the API version as a query string parameter with the request, which is the default versioning scheme accepted by the Asp.Versioning.Mvc library. There are other schemes too that we would discuss later in an upcoming article, but now add version 2 of the “testmethod” endpoint. For that, the approach that you would use is to add another controller class as shown below with the same route “api/test” as the former, but this time you would pass “2.0” as the parameter to ApiVersion attribute as shown below.

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

namespace ApiVersioningDemoInNet7.Controllers
{
 
    [ApiVersion("2.0")]
    [Route("api/test")] 
    [ApiController] 
    public class Test2Controller : ControllerBase
    {
        [HttpGet, Route("testmethod")]
        public string TestMethod()
        {
            return "Test method V2 call successful";
        }
    }
}

Now it is time to test both the versions of API endpoint. Repeat the test after running the project by typing https://localhost:{port}/api/test/testmethod?api-version=1.0 (replace {port} with correct value) on the browser’s address bar and then hit enter. As earlier the browser should display "Test method call successful”. Now pass “2.0” as the value of the api-version query string parameter. The browser should display "Test method V2 call successful”. Congratulations! you have two versions of your sample API endpoint running in parallel. Now when you check the value of Api-Supported-Versions in response headers, it should display “1.0, 2.0”. This information helps client app developers to get informed about the versions available for an API.

Now that you know how to implement API versioning, it is time to look into a specific problem your team may face if you’ve not started versioning your API from day one. Let’s say your unversioned API is already running in production, and now because of the problems versioning could solve your team has taken a conscious decision to implement it. How do you ensure that existing client apps that do not pass the version parameter with API requests are not disrupted?

DefaultApiVersion and AssumeDefaultVersionWhenUnspecified property configurations as shown below can come to your rescue. AssumeDefaultVersionWhenUnspecified property when set to true

routes any request without version information to the version as set as the value of the DefaultApiVersion property. After the below configuration, all the unversioned API calls would be directed to endpoints with version 1.0. Make the below changes, run the application, and test the application by making unversioned (do not pass api-version parameter) API calls and also make sure the versioned API calls are still working.

services.AddApiVersioning(setup =>
{
	setup.DefaultApiVersion = new ApiVersion(1, 0);
	setup.AssumeDefaultVersionWhenUnspecified = true;**
	setup.ReportApiVersions = true;
}).AddMvc();

The completed code can be found in the “Milestone 1/SeparateControllerClasses” folder of the accompanying Git repository.

Wrapping Up

Congrats! you have made it to the end of this article on API versioning. In this article, you saw a quick but nifty way of implementing API versioning in a .Net web API application using the Asp.Versioning.Mvc library. You also saw how to keep the API already running in production backward compatible in scenarios when you incorporate versioning into it at a later time.

If you are interested in delving into topics like how different versions can be organized and configured, and different versioning schemes supported by Asp.Versioning.Mvc library, you can find an article here.