Version Management with ASP.NET API Versioning

What is ASP.NET API Versioning?

ASP.NET API Versioning is a powerful process that allows you to manage multiple versions of your APIs simultaneously. In software architecture, versioning enables you to add new features and perform bug fixes while maintaining the backward compatibility of applications that use the API. ASP.NET API Versioning is critically important for sustainability and flexibility in both large projects and growing applications.

Why is API Versioning Done?

Making changes to APIs is inevitable. Especially in continuously updated and growing projects, it is important that users receive new features without breaking older versions. Thanks to versioning, multiple versions of your API can work together, and older clients can safely continue to use the service. Additionally, the development team can work more flexibly on the codebase and propagate changes in a controlled manner.

How to Install ASP.NET API Versioning?

In ASP.NET Core projects, it can be easily installed with the Microsoft.AspNetCore.Mvc.Versioning NuGet package. After installation, you can assign versions per controller or action to manage different versions. Below you can see a basic installation example:

// Installation is done with the following command in NuGet:// dotnet add package Microsoft.AspNetCore.Mvc.Versioning// In Program.cs or Startup.cs:services.AddApiVersioning(options => {    options.DefaultApiVersion = new ApiVersion(1, 0);    options.AssumeDefaultVersionWhenUnspecified = true;    options.ReportApiVersions = true;});

How are API Versions Defined?

Versions can be defined at the controller level as attributes. For example, a controller with two different versions is written as follows:

[ApiController][Route("api/v{version:apiVersion}/[controller]")][ApiVersion("1.0")]public class ProductsController : ControllerBase{    [HttpGet]    public IActionResult GetV1() => Ok("V1 Product List");}[ApiController][Route("api/v{version:apiVersion}/[controller]")][ApiVersion("2.0")]public class ProductsV2Controller : ControllerBase{    [HttpGet]    public IActionResult GetV2() => Ok("V2 Product List");}

How is Version Information Sent?

API clients can usually send version information through the URL, request headers, or as a query parameter. One of the most common methods is URL-based:

GET /api/v1/Products
GET /api/v2/Products

Conclusion

ASP.NET API Versioning ensures that your API remains manageable, flexible, and sustainable in the long term. When needed, versioning offers great convenience to meet the continuity expectations of current users while making innovations in the API. Version management with ASP.NET API Versioning represents an indispensable building block for anyone who wants to develop modern web services.