Implementing API Versioning in ASP.NET Core Web API

Introduction

As APIs evolve, changes and improvements can lead to breaking changes. API versioning helps maintain backward compatibility while enabling new features. ASP.NET Core provides built-in support for API versioning, making it easy to maintain different versions of the API efficiently.

In this blog post, I am touching base upon different ways to implement API versioning in ASP.NET Core Web API. Let's start with the first and the most important part.

Setting Up API Versioning in ASP.NET Core

To get started, let's first install the required NuGet package:

Install-Package Asp.Versioning.Mvc

Once installed, configure API versioning in the Program.cs file:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;
var builder = WebApplication.CreateBuilder(args);

// Add API versioning services
builder.Services.AddApiVersioning(options => {

options.ReportApiVersions = true;
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ApiVersionReader = new UrlSegmentApiVersionReader();

});

builder.Services.AddControllers();
var app = builder.Build();
app.UseAuthorization();
app.MapControllers();
app.Run();

Implementing Versioned Controllers

Now, let’s create two versions of a ProductsController.

Version 1 (v1) of ProductsController

[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("1.0")]
public class ProductsV1Controller : ControllerBase
{
[HttpGet]
public IActionResult GetProducts()
{
 return Ok(new string[] { "Product A", "Product B" });
  }
}

Version 2 (v2) of ProductsController with Additional Data

[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("2.0")]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult GetProducts()  
 {
      return Ok(new { Products = new[] { "Product X", "Product Y" }, 
            TotalCount = 2 });
  }
}

Testing API Versioning

You can test the API using the following URLs:

1. Version 1: GET /api/v1/products
2. Version 2: GET /api/v2/products

Each version returns different responses, ensuring backward compatibility while allowing newer features.

Alternative Versioning Strategies

Besides URL-based versioning, ASP.NET Core supports other approaches:

1. Query String Versioning

Modify Program.cs to use query string versioning:

options.ApiVersionReader = new QueryStringApiVersionReader("api-version");

Call API using:

2. Header-Based Versioning

Modify Program.cs to use custom headers:

options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version");

Set header when calling the API:

Conclusion

API versioning is crucial for maintaining backward compatibility while allowing improvements in newer versions. ASP.NET Core makes it easy to implement versioning using URL segments, query strings, or headers.

By following this approach, you ensure a smooth transition for API consumers as your application evolves.

🚀 Happy coding!