.NET API versioning

dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new HeaderApiVersionReader("Api-Version"),
        new QueryStringApiVersionReader("api-version")
    );
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public IActionResult GetV1() => Ok(new { Id = 1, Name = "Legacy Product" });

    [HttpGet]
    [MapToApiVersion("2.0")]
    public IActionResult GetV2() => Ok(new { Id = 1, Name = "Legacy Product", Category = "Electronics" });
}

lete versions explicitly:

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase { ... }

When Deprecated = true is set, the framework automatically includes Sunset and Deprecation headers in responses. Configure sunset timing globally:

options.ApiVersionReader = new HeaderApiVersionReader("Api-Version");
options.UseApiBehavior = true;

Step 4: OpenAPI Integration

Generate versioned documentation using Swashbuckle or NSwag:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo
        {
            Title = $"Product API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
            Description = description.IsDeprecated ? "This version is deprecated." : ""
        });
    }
});

This generates separate Swagger UI endpoints (/swagger/v1.0/swagger.json, /swagger/v2.0/swagger.json) aligned with resolved versions.

Architecture Rationale

• Declarative over Imperative: Attributes keep versioning logic close to the contract definition, avoiding scattered routing middleware.
• Explicit Resolution: AssumeDefaultVersionWhenUnspecified = true prevents 400 errors for legacy clients while maintaining strict version tracking.
• Version-Aware Documentation: IApiVersionDescriptionProvider ensures OpenAPI specs reflect actual resolved versions, enabling accurate client SDK generation.

Pitfall Guide

1. Versioning Implementation Details Instead of Contracts

Developers frequently version controllers based on internal refactoring (e.g., switching from EF Core to Dapper) rather than consumer-facing contract changes. Version boundaries should only exist when request/response shapes, authentication flows, or error semantics change. Internal implementation changes belong behind the same version contract.

2. Silent Breaking Changes

Modifying a response DTO by removing a field, changing a type, or altering nullability without incrementing the version causes client deserialization failures. Always maintain backward compatibility within a version. Additive changes are safe; subtractive or type-changing changes require a new version.

3. Mixing Versioning Strategies in the Same Surface

Combining URL path versioning (/api/v1/) with header-based resolution (Api-Version: 2) in the same API surface creates routing ambiguity and breaks OpenAPI path generation. Choose one primary transport per API group and enforce it through middleware or gateway policies.

4. Ignoring Deprecation Lifecycle

Removing a version without signaling deprecation violates HTTP semantics and breaks automated client retries. Always set Deprecated = true, configure Sunset headers with a migration window, and monitor usage metrics before removal. Production systems should return 410 Gone only after the sunset period expires.

5. Over-Relying on URL Path Versioning for Microservices

URL path versioning fragments cache keys, increases CDN costs, and complicates service mesh routing tables. Internal services should prefer header-based versioning to preserve resource identity and enable efficient caching at the gateway layer.

6. Treating Versioning as a Routing Problem

Versioning is a contract negotiation mechanism, not a URL pattern. Routing configuration should reflect resolved versions, not drive them. When versioning logic lives in route templates, the framework cannot enforce deprecation policies, report version usage, or generate accurate OpenAPI specs.

7. Neglecting Version-Aware Monitoring

Without version-specific telemetry, teams cannot measure migration progress or detect client stagnation. Instrument requests with Api-Version tags in Application Insights or OpenTelemetry. Track version distribution, error rates per version, and sunset compliance to drive migration automation.

Best Practices from Production:

• Enforce contract testing (Pact, WireMock) per version before deployment
• Use API gateways to enforce version headers and reject unsupported versions at the edge
• Automate client SDK generation from versioned OpenAPI specs
• Maintain a version migration dashboard tied to telemetry
• Deprecate, don't delete: keep obsolete versions operational during migration windows

Production Bundle

Action Checklist

• Install Microsoft.AspNetCore.Mvc.Versioning and ApiExplorer packages
• Configure ApiVersioningOptions with default version, resolution strategy, and deprecation reporting
• Apply [ApiVersion] and [MapToApiVersion] attributes to controllers and actions
• Enable ReportApiVersions to expose api-supported-versions and api-deprecated-versions headers
• Integrate IApiVersionDescriptionProvider with Swagger/NSwag for versioned documentation
• Instrument telemetry with version tags and track migration progress
• Configure API gateway to validate version headers and route to correct backend versions

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Public B2C API	URL Path (/api/v1/)	Discoverable, browser-friendly, SEO-compatible, SDK generation aligns with path structure	Medium (CDN cache fragmentation)
Internal Microservices	Header (Api-Version: 1)	Preserves resource identity, enables aggressive caching, reduces routing complexity	Low (minimal infrastructure overhead)
B2B Partner Integration	Query String (?api-version=1)	Easy to test in browsers, backward-compatible with legacy HTTP clients, simple gateway passthrough	Low (negligible, but complicates OpenAPI paths)
Rapid Prototyping / MVP	URL Path with assumed default	Fastest to implement, aligns with developer expectations, easy to migrate to header later	Low (technical debt if not formalized)

Configuration Template

// Program.cs
using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new HeaderApiVersionReader("Api-Version"),
        new QueryStringApiVersionReader("api-version")
    );
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo
        {
            Title = $"Sample API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
            Description = description.IsDeprecated ? "Deprecated. Migrate to latest version." : ""
        });
    }
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Quick Start Guide

1. Install packages: dotnet add package Microsoft.AspNetCore.Mvc.Versioning Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
2. Add AddApiVersioning() and AddVersionedApiExplorer() to service registration with header/query fallback
3. Decorate controllers with [ApiVersion("1.0")] and actions with [MapToApiVersion("1.0")]
4. Run the application and test with curl -H "Api-Version: 1.0" https://localhost:5001/api/products
5. Verify version headers in response: api-supported-versions: 1.0, 2.0 and api-deprecated-versions: (empty unless marked deprecated)