API Versioning in .NET 6

Introduction

In the fast-paced world of software development, change is the only constant. And when it comes to developing APIs, ensuring that those changes don't disrupt existing client applications is paramount. Enter API versioning – a technique that allows you to enhance and upgrade your API while maintaining harmony with the past. Today, we'll explore the why and how of API versioning in the context of .NET 6.

Three Pillars of API Versioning

API versioning is the cornerstone of API evolution, and it offers three compelling benefits that underscore its importance.

1. Seamless Coexistence: Imagine this scenario: your API has been serving clients for years, and they rely on its structure and behavior. With API versioning, different iterations of your API can peacefully coexist. This means that while you're introducing exciting new features and improvements for modern clients, your older clients can continue to operate without disruption. It's a win-win situation.
2. Controlled Evolution: As your API matures and evolves, keeping track of changes becomes crucial. API versioning provides you with a structured way to manage these changes. With each version, you document what's new, what's modified, and what remains unchanged. This not only helps developers understand the API's progression but also empowers them to make informed decisions about which version best suits their needs.
3. Granular Control: One size does not fit all in the API world. You might want to selectively expose new features to specific client applications while keeping others on older versions. API versioning offers granular control over which version of an endpoint a client can access. This means you can tailor the API experience to suit the capabilities and requirements of different client applications, ensuring optimal compatibility.

A Journey in Four Steps

In just four simple steps, we will unlock a world of possibilities.

1. Installing the Package

It all begins with a simple installation. By adding the necessary versioning package to your project from Nuget.

Microsoft.AspNetCore.Mvc.Versionin

2. Configuring Program.cs

Next, you configure your Program.cs file to integrate versioning into your API. This step ensures that your API is version-aware right from the start.

app.UseEndpoints(endpoints =>
{
    app.MapHealthChecks("/DemoApi/health");
    endpoints.MapControllers();

    endpoints.MapControllerRoute(
        name: "default",
        pattern: "DemoApi/api/v{version:apiVersion}/{controller}/{action}"
    );
});

app.MapControllers();

3. Adding Versions to Controllers

With versioning in place, you can easily add versions to your controllers by annotating your controller API Version attribute and Pass the Route attribute. This process allows you to maintain multiple versions of your API endpoints.

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

4. ApiController Code

Here is the sample code you can add to your project to test whether the Versioning is working or not.

using Microsoft.AspNetCore.Mvc;
using System;

namespace DemoApi.Service.Controllers
{
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    [Route("DemoApi/api/v{version:apiVersion}/[controller]")]
    public class DemoAPIController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetAPIVersion(ApiVersion apiVersion)
        {
            try
            {
                return Ok($"API Version: {apiVersion.ToString()}");
            }
            catch (Exception ex)
            {
                return StatusCode(500, ex.Message);
            }
        }
    }
}

5. Testing with Postman

To ensure everything is working as expected, testing is crucial. Postman, a popular API testing tool, comes to the rescue here. It allows you to validate the functionality and compatibility of your newly versioned API.

http://localhost:32860/DemoApi/api/v1/DemoAPI

http://localhost:32860/DemoApi/api/v2/DemoAPI

Conclusion

API versioning in .NET 6 is not just a technical maneuver; it's a strategy for future-proofing your APIs. It ensures that your APIs gracefully evolve with the changing landscape of software development, all while preserving the integrity of existing client applications.

😊Please consider liking and following me for more articles and if you find this content helpful.👍