Api Versioning

// Program.csbuilder.Services.AddApiVersioning(options =>{    options.DefaultApiVersion = new ApiVersion(1, 0);    options.AssumeDefaultVersionWhenUnspecified = true;    options.ReportApiVersions = true;    options.ApiVersionReader = new UrlSegmentApiVersionReader();}).AddApiExplorer(options =>{    options.GroupNameFormat = "'v'VVV";    options.SubstituteApiVersionInUrl = true;});

var v1 = app.NewApiVersionSet()    .HasApiVersion(new ApiVersion(1, 0))    .Build();
var v2 = app.NewApiVersionSet()    .HasApiVersion(new ApiVersion(2, 0))    .Build();
app.MapGroup("/api/v{version:apiVersion}/orders")    .WithApiVersionSet(v1)    .WithTags("Orders")    .MapOrderEndpointsV1();
app.MapGroup("/api/v{version:apiVersion}/orders")    .WithApiVersionSet(v2)    .WithTags("Orders")    .MapOrderEndpointsV2();

options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
// Client sends: X-Api-Version: 2.0

var v1 = app.NewApiVersionSet()    .HasDeprecatedApiVersion(new ApiVersion(1, 0))    .HasApiVersion(new ApiVersion(2, 0))    .Build();
// Response headers will include: api-deprecated-versions: 1.0

public static class OrderEndpointsV1{    public static RouteGroupBuilder MapOrderEndpointsV1(this RouteGroupBuilder group)    {        group.MapGet("/{id:guid}", GetOrderV1);        group.MapPost("/", CreateOrderV1);        return group;    }
    private static async Task<Results<Ok<OrderResponseV1>, NotFound>> GetOrderV1(        Guid id, ISender sender, CancellationToken ct)    {        // V1 response shape        var result = await sender.Send(new GetOrder.Query(id), ct);        return result.IsSuccess            ? TypedResults.Ok(result.Value.ToV1())            : TypedResults.NotFound();    }}
public static class OrderEndpointsV2{    public static RouteGroupBuilder MapOrderEndpointsV2(this RouteGroupBuilder group)    {        group.MapGet("/{id:guid}", GetOrderV2);        group.MapPost("/", CreateOrderV2);        return group;    }
    private static async Task<Results<Ok<OrderResponseV2>, NotFound>> GetOrderV2(        Guid id, ISender sender, CancellationToken ct)    {        // V2 response shape — includes new fields        var result = await sender.Send(new GetOrder.Query(id), ct);        return result.IsSuccess            ? TypedResults.Ok(result.Value.ToV2())            : TypedResults.NotFound();    }}

// BAD — inconsistent versioning within a groupapp.MapGet("/api/v1/orders", ListOrdersV1);app.MapGet("/api/v2/orders/{id}", GetOrderV2); // V2 only for this endpoint?
// GOOD — version the entire groupapp.MapGroup("/api/v1/orders").MapOrderEndpointsV1();app.MapGroup("/api/v2/orders").MapOrderEndpointsV2();

// BAD for REST APIs — version hidden in query string, not cache-friendlyGET /api/orders?api-version=2.0
// GOOD — version in URL, discoverable and cacheableGET /api/v2/orders