API Versioning

dotnet add package Asp.Versioning.Mvc

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

Common follow-ups: What are the different strategies for exposing a version (URL, header, query string)?;How do you decide when a change is breaking enough to warrant a new version?

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase {
    [HttpGet]
    public IActionResult Get() => Ok(_v1Products);
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase {
    [HttpGet]
    public IActionResult Get() => Ok(_v2ProductsWithNewFields);
}

Common follow-ups: How do you share common logic between V1 and V2 controllers without duplication?;What happens if a client requests a version that doesn't exist?

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .ReportApiVersions()
    .Build();

var group = app.MapGroup("api/v{version:apiVersion}/products").WithApiVersionSet(versionSet);

group.MapGet("/", () => Ok(v1Products)).HasApiVersion(1.0);
group.MapGet("/", () => Ok(v2Products)).HasApiVersion(2.0);

Common follow-ups: How does WithApiVersionSet differ from applying versioning per individual endpoint?;Can minimal APIs and controllers share the same versioning configuration in one app?

builder.Services.AddApiVersioning(options => {
    options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
});

// Client request:
// GET /api/products/5
// X-Api-Version: 2.0

Common follow-ups: How do you combine multiple version readers (URL AND header) simultaneously?;What are the caching implications of header-based versus URL-based versioning?

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase { }

// Every response now includes:
// api-deprecated-versions: 1.0
// api-supported-versions: 1.0, 2.0

Common follow-ups: How long is a reasonable deprecation window before removing a version entirely?;How would you notify consumers through channels beyond just response headers?

[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase {
    [HttpGet]
    public IActionResult GetAll() => Ok(_products);  // available in both 1.0 and 2.0

    [HttpGet("{id}/reviews")]
    [MapToApiVersion("2.0")]
    public IActionResult GetReviews(int id) => Ok(_reviews);  // only in 2.0
}

Common follow-ups: What happens if MapToApiVersion references a version not declared on the controller?;When does splitting into fully separate controllers become clearer than this shared approach?

builder.Services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;  // unversioned requests silently get v1.0
});

// Without AssumeDefaultVersionWhenUnspecified:
// An unversioned request instead returns 400 Bad Request

Common follow-ups: What's the risk of silently defaulting unversioned requests to the latest version instead of a fixed default?;How do public versus internal APIs typically differ in this choice?

[Fact]
public void GetAll_V2_ReturnsExpandedProductFields() {
    var controller = new ProductsV2Controller(_mockService.Object);
    var result = controller.GetAll() as OkObjectResult;
    var products = result.Value as List<ProductV2Dto>;
    Assert.Contains(products, p => p.Currency != null);  // v2-specific field
}

Common follow-ups: What would an integration test verifying correct version routing look like?;How do you test the deprecation header behavior specifically?

// Public API: formal versioning, months of overlap
[ApiVersion("1.0", Deprecated = true)]  // still supported 12+ months after v2 launch
[ApiVersion("2.0")]

// Internal API: looser, relies on coordinated deploys + contract tests instead
// often no formal API versioning attributes at all

Common follow-ups: What is consumer-driven contract testing and how does it substitute for formal versioning internally?;What risk does an internal API accept by skipping formal versioning?

builder.Services.AddApiVersioning(options => {
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

// GET /api/products?api-version=2.0

Common follow-ups: How does this interact with CDN or reverse-proxy caching that might ignore query strings?;Why is URL segment versioning generally considered more RESTful/discoverable?