klod68/api-versioning-strategy

---

name: api-versioning-strategy description: "Use when adding versioning to HTTP APIs, introducing a breaking change to an existing API contract, or when you need to deprecate an old API version with a sunset protocol. Covers URL segment, query string, header, and media type strategies, Asp.Versioning setup, deprecation headers with Sunset dates, and breaking vs. additive change classification rules. Domain: API Design, REST. Level: Intermediate. Tags: api-versioning, rest, breaking-changes, deprecation, minimal-api."

API Versioning Strategy

Problem

APIs evolve over time. Without explicit versioning, breaking changes cause consumer failures, and teams resort to ad-hoc workarounds like V2 suffixes on endpoints or parallel controllers.

Solution: Choose One Strategy, Apply Consistently

Select a versioning strategy based on your API's audience. Default unversioned requests to the latest stable version. Deprecate old versions with headers and sunset dates.

Strategy Comparison

| Strategy | URL Shape | Pros | Cons | Best For | |----------|-----------|------|------|----------| | URL Segment | /api/v1/orders | Simple, visible, cacheable | URL changes on version bump | Public APIs, REST | | Query String | /api/orders?api-version=1.0 | URL stable, easy to add | Easy to forget, less visible | Internal APIs | | Header | X-Api-Version: 1.0 | Clean URLs, no routing changes | Invisible, harder to test | Internal microservices | | Media Type | Accept: application/vnd.myapp.v1+json | RESTful, content negotiation | Complex, harder to document | Hypermedia APIs |

Decision Guide

• Public REST APIs: URL segment versioning (most discoverable)
• Internal microservices: Header versioning (clean URLs, no routing duplication)
• Default: URL segment unless you have a strong reason otherwise

Implementation (.NET)

1. Install Package

<PackageReference Include="Asp.Versioning.Http" Version="8.1.0" />
<!-- For MVC: Asp.Versioning.Mvc -->
<!-- For MVC + API Explorer: Asp.Versioning.Mvc.ApiExplorer -->

2. Configure Versioning

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true; // Adds api-supported-versions header
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version")
    );
});

3. Minimal API — URL Segment

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

var v1 = app.MapGroup("api/v{version:apiVersion}/orders")
    .WithApiVersionSet(versionSet)
    .MapToApiVersion(new ApiVersion(1, 0));

var v2 = app.MapGroup("api/v{version:apiVersion}/orders")
    .WithApiVersionSet(versionSet)
    .MapToApiVersion(new ApiVersion(2, 0));

v1.MapGet("/", OrderEndpointsV1.GetAll);
v2.MapGet("/", OrderEndpointsV2.GetAll);

4. MVC Controller

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class OrdersController : ControllerBase
{
    [HttpGet, MapToApiVersion("1.0")]
    public IActionResult GetV1() { /* ... */ }

    [HttpGet, MapToApiVersion("2.0")]
    public IActionResult GetV2() { /* ... */ }
}

Deprecation Protocol

1. Mark version as deprecated (response header: api-deprecated-versions: 1.0).
2. Add Sunset header with removal date: Sunset: Sat, 01 Nov 2026 00:00:00 GMT.
3. Document migration guide from deprecated → current version.
4. Monitor usage of deprecated versions — don't remove until traffic drops to zero.
5. Remove deprecated version after sunset date.

Breaking vs. Additive Changes

| Change Type | Version Bump? | Examples | |---|---|---| | Breaking (new version) | Yes | Removed field, renamed field, changed type, changed behavior | | Additive (same version) | No | New optional field, new endpoint, new optional parameter |

When to Use

• Any HTTP API (REST, RPC-over-HTTP) with external consumers
• Internal APIs with multiple consumer teams on different release cycles
• APIs that need to evolve without breaking existing clients

When NOT to Use

• Single-consumer internal APIs where both sides deploy together
• gRPC services (use protobuf package versioning instead)
• Event-driven systems (version the event schema, not the API)

Gotchas

1. One versioning strategy per API — don't mix URL segment and header in the same API.
2. Version the contract, not the implementation — internal refactoring doesn't require a new version.
3. Always report supported versions via api-supported-versions response header.
4. Never remove a version without a sunset period (minimum 6 months for public APIs).
5. Test all active versions in CI — deprecated versions still need to work until sunset.

Related Skills

• Gen Minimal API Endpoint (scaffold versioned endpoint groups)
• Health Check Endpoint (health checks should not be versioned)