API Versioning

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
builder.Services.AddControllers();

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

        // Deprecation: @<epoch> plus Link: <...>; rel="deprecation"
        options.Policies.Deprecate(1.0)
            .Effective(new DateTimeOffset(2026, 10, 1, 0, 0, 0, TimeSpan.Zero))
            .Link("https://developer.example.com/orders/v1-deprecation")
                .Title("Orders API v1 deprecation")
                .Type("text/html");

        // Sunset: Wed, 31 Mar 2027 00:00:00 GMT plus Link: <...>; rel="sunset"
        options.Policies.Sunset(1.0)
            .Effective(new DateTimeOffset(2027, 3, 31, 0, 0, 0, TimeSpan.Zero))
            .Link("https://developer.example.com/orders/migrate-to-v2")
                .Title("Migrating to Orders API v2")
                .Type("text/html");
    })
    .AddMvc()
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";          // v1, v2
        options.SubstituteApiVersionInUrl = true;    // documents show /api/v2/orders
    });

var app = builder.Build();

app.MapControllers();

// Minimal APIs in the same app, versioned the same way.
var products = app.NewVersionedApi("Products");
var productsV1 = products.MapGroup("/api/v{version:apiVersion}/products").HasDeprecatedApiVersion(1.0);
var productsV2 = products.MapGroup("/api/v{version:apiVersion}/products").HasApiVersion(2.0);

productsV1.MapGet("/{sku}", (string sku) => new { sku, price = 39.95m });
productsV2.MapGet("/{sku}", (string sku) => new { sku, price = new Money(39.95m, "EUR") });

app.Run();

public record Money(decimal Amount, string Currency);
public record OrderV1(int Id, string CustomerId, decimal Total);
public record OrderV2(int Id, string CustomerId, Money Total, string Status);

[ApiController]
[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/orders")]
public sealed class OrdersController : ControllerBase
{
    // GET /api/v1/orders/1001 -> total is a number
    [HttpGet("{id:int}")]
    [MapToApiVersion(1.0)]
    public ActionResult<OrderV1> GetV1(int id) => new OrderV1(id, "CUST-1042", 79.90m);

    // GET /api/v2/orders/1001 -> total carries its currency
    [HttpGet("{id:int}")]
    [MapToApiVersion(2.0)]
    public ActionResult<OrderV2> GetV2(int id) =>
        new OrderV2(id, "CUST-1042", new Money(79.90m, "EUR"), "Paid");
}