API Versioning

// v1: returns { name: string }
// v2: returns { firstName: string, lastName: string }
// Both versions coexist so old clients keep working during a migration window

Common follow-ups: What's the difference between a breaking and non-breaking API change?;How long should old versions typically be supported?

// URL segment (most common)
[Route("api/v{version:apiVersion}/products")]

// Query string
// GET /api/products?api-version=1.0

// Header
// GET /api/products  Header: X-Api-Version: 1.0

Common follow-ups: Which strategy works best with CDN and reverse-proxy caching?;How do you combine multiple versioning strategies simultaneously?

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

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase { }

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase { }

Common follow-ups: How do you deprecate a version and communicate it via response headers?;How does versioning interact with Swagger/OpenAPI documentation generation?

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

    [HttpGet("{id}")]
    [MapToApiVersion("2.0")]
    public IActionResult GetByIdV2(int id) => Ok(_v2Format);  // only in v2
}

Common follow-ups: What happens if a request doesn't match any MapToApiVersion action?;How does this compare to maintaining fully separate controllers per version?

builder.Services.AddApiVersioning(options => {
    options.ReportApiVersions = true;  // adds api-supported-versions / api-deprecated-versions headers
});

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase { }

Common follow-ups: How far in advance should deprecation typically be announced?;What HTTP status code should a fully removed version return?

// Internal domain model can change freely
public class ProductEntity { public decimal Price { get; set; } public string Currency { get; set; } }

// v1 DTO stays stable regardless of internal changes
public class ProductV1Dto { public decimal Price { get; set; } }  // USD assumed

// v2 DTO exposes the new capability
public class ProductV2Dto { public decimal Amount { get; set; } public string Currency { get; set; } }

Common follow-ups: How does this relate to the Anti-Corruption Layer pattern?;What's the maintenance cost of keeping many DTO versions in sync?

// Externally exposed: only major version
// /api/v1/products  /api/v2/products

// Internally tracked via SemVer in release notes:
// v1.3.2 -- patch fix, no client action needed
// v1.4.0 -- new optional field added, backward compatible
// v2.0.0 -- breaking change, new URL segment required

Common follow-ups: Should minor/patch versions ever be exposed in the URL?;How does this map to versioning conventions in package managers like NuGet?

// Server adds a new optional field without a version bump:
{ "id": 1, "name": "Widget", "weightKg": 2.5 }  // new field

// Tolerant client (e.g., using JsonSerializerOptions with unmapped members ignored)
var options = new JsonSerializerOptions {
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip
};

Common follow-ups: What are the risks of being too tolerant (silently ignoring meaningful changes)?;How does this principle relate to Postel's Law?

builder.Services.AddSwaggerGen();
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();

app.UseSwaggerUI(options => {
    foreach (var description in provider.ApiVersionDescriptions)
        options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
});

Common follow-ups: How does ConfigureSwaggerOptions discover registered API versions automatically?;What happens to Swagger docs when a version is removed?

// Global versioning: entire API bumps together
// /api/v2/products  /api/v2/orders  /api/v2/customers (all v2, even if only products changed)

// Independent versioning: only the changed resource bumps
// /api/v1/orders  /api/v2/products  /api/v1/customers (mixed versions)

Common follow-ups: Which large public APIs use each approach (e.g., Stripe vs GitHub)?;How does independent versioning complicate client SDK generation?