Back
ASP.NET Core API Versioning

ASP.NET Core API Versioning

Learn different API versioning strategies in ASP.NET Core

Why API Versioning?

API versioning is essential for maintaining backward compatibility and managing updates.

  • Prevents breaking changes for existing clients.
  • Allows smooth transitions to newer API versions.
Versioning Strategies
  • URI Versioning: /api/v1/products
  • Query String Versioning: /api/products?api-version=1.0
  • Header Versioning: X-API-Version: 1.0
  • Media Type Versioning: Accept: application/json; version=1.0

Why API Versioning is Essential

  • Backward Compatibility: Maintain existing client functionality.
  • Controlled Evolution: Manage API changes systematically.
  • Client Flexibility: Allow clients to choose their API version.
Implementation in ASP.NET Core
Step 1: Install API Versioning Package
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
Step 2: Configure API Versioning
builder.Services.AddApiVersioning(options => {
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});
Step 3: Apply Versioning to Controllers
[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("1.0")]
public class ProductsV1Controller : ControllerBase {
    [HttpGet]
    public IActionResult Get() => Ok("Products from v1");
}