1// Install: dotnet add package Asp.Versioning.Mvc (ASP.NET Core 9)
2
3// Program.cs
4builder.Services.AddApiVersioning(options =>
5{
6    // What version to assume when none is specified
7    options.DefaultApiVersion = new ApiVersion(1, 0);
8    options.AssumeDefaultVersionWhenUnspecified = true;
9
10    // Include api-supported-versions / api-deprecated-versions in response headers
11    options.ReportApiVersions = true;
12
13    // Choose your strategy (or combine multiple readers with ApiVersionReader.Combine)
14    options.ApiVersionReader = ApiVersionReader.Combine(
15        new UrlSegmentApiVersionReader(),
16        new HeaderApiVersionReader("api-version"),
17        new QueryStringApiVersionReader("api-version")
18    );
19}).AddMvc();
20
21// Controller: multiple versions on one class, or split into separate classes
22[ApiController]
23[Route("api/v{version:apiVersion}/orders")]
24[ApiVersion("3.0")]
25[ApiVersion("2.0", Deprecated = true)]   // still works, but sends Sunset/Deprecation headers
26public class OrdersController : ControllerBase
27{
28    private readonly ILogger<OrdersController> _logger;
29
30    public OrdersController(ILogger<OrdersController> logger) => _logger = logger;
31
32    [HttpGet("{orderId:guid}")]
33    [MapToApiVersion("3.0")]
34    public async Task<IActionResult> GetOrderV3(
35        Guid orderId,
36        CancellationToken cancellationToken)
37    {
38        // V3 includes nested line items and fulfillment status
39        var order = await _orderService.GetWithLineItemsAsync(orderId, cancellationToken);
40        if (order is null) return NotFound();
41        return Ok(new OrderV3Response(order));
42    }
43
44    [HttpGet("{orderId:guid}")]
45    [MapToApiVersion("2.0")]
46    public async Task<IActionResult> GetOrderV2(
47        Guid orderId,
48        CancellationToken cancellationToken)
49    {
50        _logger.LogWarning(
51            "Client called deprecated v2 endpoint for order {OrderId}. " +
52            "TraceId: {TraceId}",
53            orderId, HttpContext.TraceIdentifier);
54
55        var order = await _orderService.GetAsync(orderId, cancellationToken);
56        if (order is null) return NotFound();
57        return Ok(new OrderV2Response(order));  // old response shape
58    }
59}
60
61// Version-neutral endpoint (no versioning applied — e.g. health checks)
62[ApiController]
63[ApiVersionNeutral]
64[Route("health")]
65public class HealthController : ControllerBase
66{
67    [HttpGet] public IActionResult Get() => Ok(new { status = "healthy" });
68}
69
70// Minimal API version sets (ASP.NET Core 7+ / Asp.Versioning 7+)
71var versionSet = app.NewApiVersionSet()
72    .HasApiVersion(new ApiVersion(3, 0))
73    .HasApiVersion(new ApiVersion(4, 0))
74    .HasDeprecatedApiVersion(new ApiVersion(2, 0))
75    .ReportApiVersions()
76    .Build();
77
78app.MapGet("/api/products/{id}", GetProduct)
79   .WithApiVersionSet(versionSet)
80   .MapToApiVersion(new ApiVersion(4, 0));