API Versioning In ASP.NET Core

API versioning in ASP.NET Core is an important practice to manage multiple versions of your API efficiently, ensuring backward compatibility and smooth transitions for clients using older versions. Here's a comprehensive guide on how to implement API versioning in ASP.NET Core.

Steps to Implement API Versioning

Add the Required NuGet Package

Install the Microsoft.AspNetCore.Mvc.Versioning package to add API versioning support.

Configure API Versioning in Startup.cs (or Program.cs for .NET 6+)

Add API versioning services to the DI container.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // Add API versioning
    services.AddApiVersioning(options =>
    {
        // Use the default version if none is specified
        options.AssumeDefaultVersionWhenUnspecified = true;

        // Set the default API version (e.g., 1.0)
        options.DefaultApiVersion = new ApiVersion(1, 0);

        // Include API versions in the response headers
        options.ReportApiVersions = true;
    });
}

Define Versioned Controllers

Annotate your controllers with the desired API version using the [ApiVersion] attribute.

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]  // Version 1.0
public class EmployeesController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("This is version 1.0 of the Employees API");
    }
}

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]  // Version 2.0
public class EmployeesV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("This is version 2.0 of the Employees API");
    }
}

Enable Versioning in the API Routes

ASP.NET Core allows different ways to specify the version in the request.

Annotate your controllers with the desired API version using the [ApiVersion] attribute.

URL Versioning (Recommended)

Include the version in the URL as a route parameter.

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

Query String Versioning

Configure query string versioning.

services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new QueryStringApiVersionReader("v");
});

The client side specifies the version as a query parameter: /api/employees?v=1.0.

Header Versioning

Configure header-based versioning.

services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
});

The client side specifies the version in the request header.

x-api-version: 1.0

Media Type Versioning

Use media types to specify the version.

services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new MediaTypeApiVersionReader("v");
});

The client side specifies the version in the Accept header.

Accept: application/json; v=1.0

Example. Testing the Versioning

1. Version 1.0 (URL Versioning)
2. URL: GET /api/v1/employees
3. Version 2.0 (URL Versioning)
4. URL: GET /api/v2/employees
5. Query String Versioning
6. URL: GET /api/employees?v=1.0
7. Header Versioning
8. URL: GET /api/employees
9. Header: x-api-version: 1.0

Best Practices for API Versioning

• Start with URL versioning: It is the most explicit and easy to use.
• Plan deprecation: Clearly document and communicate when older versions will be deprecated.
• Combine with Swagger: Use Swagger for API documentation to make it easier for clients to understand available versions.
• Use feature toggles: Gradually introduce breaking changes alongside new API versions.