What is API Versioning?

API Versioning is the practice of managing changes to an API over time. As APIs evolve, new features are added, and older features might become deprecated. Versioning ensures backward compatibility for clients using older versions while providing access to new features for those on updated versions.

• Backward Compatibility: Older clients can continue to work without changes.
• Controlled Updates: New features or changes are made available in newer versions.
• Flexibility: Allows the API to evolve without breaking existing clients.

Why Use API Versioning in .NET?

API versioning is essential when you need to support multiple versions of your API for different clients or applications. .NET provides built-in support for versioning through the Microsoft.AspNetCore.Mvc.Versioning package.

How to Implement API Versioning in .NET

Follow these steps to add API versioning to your .NET project:

1. Install the Required Package

// Install the package via NuGet
Install-Package Microsoft.AspNetCore.Mvc.Versioning

                

The Microsoft.AspNetCore.Mvc.Versioning package provides tools for managing API versions.

2. Configure API Versioning

// Program.cs
var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();
app.MapControllers();
app.Run();

                

• DefaultApiVersion: Specifies the default API version.
• AssumeDefaultVersionWhenUnspecified: Assumes the default version if no version is specified.
• ReportApiVersions: Includes supported versions in the response headers.

3. Define Versioned Controllers

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

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

                

Each versioned controller is decorated with the [ApiVersion] attribute. The route includes the version parameter.

4. Test the API Versions

// Example Requests:
// GET http://localhost:5000/api/v1/products  => Returns products from version 1
// GET http://localhost:5000/api/v2/products  => Returns products from version 2

                

Use tools like Postman or a browser to test the endpoints.

Other Versioning Techniques

.NET supports multiple approaches for API versioning:

• URL Versioning: The version is specified in the URL (e.g., /api/v1/products).
• Query String Versioning: The version is passed as a query parameter (e.g., /api/products?api-version=1.0).
• Header Versioning: The version is included in a custom HTTP header (e.g., api-version: 1.0).