API Versioning in .NET 8

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package. API Versioning in .NET 8 API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package. 1. Why Use API Versioning? Backward Compatibility: Ensures old clients can still use existing endpoints while new clients can leverage updated versions. Incremental Changes: Allows adding new features without breaking existing functionality. Deprecation Strategy: You can phase out old versions systematically. 2. Installing API Versioning Package To enable API versioning in your .NET 8 Web API, install the following package: dotnet add package Microsoft.AspNetCore.Mvc.Versioning 3. Setting Up API Versioning Modify Program.cs to register versioning in the Dependency Injection (DI) container: Modify Program.cs using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Mvc.Versioning; var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); // Register API Versioning builder.Services.AddApiVersioning(options => { options.ReportApiVersions = true; // Adds API version information in response headers options.AssumeDefaultVersionWhenUnspecified = true; options.DefaultApiVersion = new ApiVersion(1, 0); // Default API version (1.0) options.ApiVersionReader = new UrlSegmentApiVersionReader(); // Versioning via URL }); var app = builder.Build(); app.UseAuthorization(); app.MapControllers(); app.Run(); 4. Applying API Versioning to Controllers You can apply API versioning using attributes. Using URL Path Versioning using Microsoft.AspNetCore.Mvc; [ApiController] [Route("api/v{version:apiVersion}/orders")] [ApiVersion("1.0")] public class OrdersV1Controller : ControllerBase { [HttpGet] public IActionResult GetOrders() { return Ok(new { Message = "Orders from v1 API" }); } } [ApiController] [Route("api/v{version:apiVersion}/orders")] [ApiVersion("2.0")] public class OrdersV2Controller : ControllerBase { [HttpGet] public IActionResult GetOrders() { return Ok(new { Message = "Orders from v2 API - New version!" }); } } Now, you can access: Version 1 API: GET /api/v1/orders Version 2 API: GET /api/v2/orders 5. Other API Versioning Strategies Besides URL versioning, you can also use: 1. Query String Versioning Modify Program.cs: options.ApiVersionReader = new QueryStringApiVersionReader("api-version"); Then, call the API: GET /api/orders?api-version=1.0 GET /api/orders?api-version=2.0 2. Header-Based Versioning Modify Program.cs: options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version"); Then, pass the version in headers: GET /api/orders X-API-Version: 2.0 6. Deprecating an API Version You can mark an API version as deprecated using: [ApiVersion("1.0", Deprecated = true)] This will inform clients that version 1.0 is obsolete. 7. Versioning via Media Type (Content-Type) Another approach is to specify the API version in the Accept header: options.ApiVersionReader = new MediaTypeApiVersionReader("v"); Then, call the API with: Accept: application/json; v=2.0 8. Combining Multiple Versioning Strategies You can allow multiple versioning mechanisms: options.ApiVersionReader = ApiVersionReader.Combine( new UrlSegmentApiVersionReader(), new QueryStringApiVersionReader("api-version"), new HeaderApiVersionReader("X-API-Version") ); This allows clients to specify the version using URL, query string, or headers. Conclusion API versioning is critical for maintaining compatibility while evolving your API. In .NET 8, Microsoft.AspNetCore.Mvc.Versioning provides multiple strategies: URL Path (/api/v1/orders) Query String (?api-version=1.0) Header (X-API-Version: 1.0) Media Type (Accept: application/json; v=1.0)

Feb 24, 2025 - 14:33

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package.

API Versioning in .NET 8

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package.

1. Why Use API Versioning?

Backward Compatibility: Ensures old clients can still use existing endpoints while new clients can leverage updated versions.
Incremental Changes: Allows adding new features without breaking existing functionality.
Deprecation Strategy: You can phase out old versions systematically.

2. Installing API Versioning Package

To enable API versioning in your .NET 8 Web API, install the following package:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

3. Setting Up API Versioning

Modify Program.cs to register versioning in the Dependency Injection (DI) container:

Modify `Program.cs`

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Register API Versioning
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;  // Adds API version information in response headers
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0); // Default API version (1.0)
    options.ApiVersionReader = new UrlSegmentApiVersionReader(); // Versioning via URL
});

var app = builder.Build();

app.UseAuthorization();
app.MapControllers();

app.Run();

4. Applying API Versioning to Controllers

You can apply API versioning using attributes.

Using URL Path Versioning

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
public class OrdersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v1 API" });
    }
}

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("2.0")]
public class OrdersV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v2 API - New version!" });
    }
}

Now, you can access:

Version 1 API: GET /api/v1/orders
Version 2 API: GET /api/v2/orders

5. Other API Versioning Strategies

Besides URL versioning, you can also use:

1. Query String Versioning

Modify Program.cs:

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

Then, call the API:

GET /api/orders?api-version=1.0
GET /api/orders?api-version=2.0

2. Header-Based Versioning

Modify Program.cs:

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

Then, pass the version in headers:

GET /api/orders
X-API-Version: 2.0

6. Deprecating an API Version

You can mark an API version as deprecated using:

[ApiVersion("1.0", Deprecated = true)]

This will inform clients that version 1.0 is obsolete.

7. Versioning via Media Type (Content-Type)

Another approach is to specify the API version in the Accept header:

options.ApiVersionReader = new MediaTypeApiVersionReader("v");

Then, call the API with:

Accept: application/json; v=2.0

8. Combining Multiple Versioning Strategies

You can allow multiple versioning mechanisms:

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new QueryStringApiVersionReader("api-version"),
    new HeaderApiVersionReader("X-API-Version")
);

This allows clients to specify the version using URL, query string, or headers.

Conclusion

API versioning is critical for maintaining compatibility while evolving your API. In .NET 8, Microsoft.AspNetCore.Mvc.Versioning provides multiple strategies:

URL Path (/api/v1/orders)
Query String (?api-version=1.0)
Header (X-API-Version: 1.0)
Media Type (Accept: application/json; v=1.0)