Lesson 27 of 40 Web Development Advanced 35 min

API Versioning & Evolution

Implement robust API versioning strategies, deprecation policies, OpenAPI multi-version documentation, and backward compatibility.

Part 1: API Versioning Setup

builder.Services.AddApiVersioning(o =>
{
  o.DefaultApiVersion = new ApiVersion(1, 0);
  o.AssumeDefaultVersionWhenUnspecified = true;
  o.ReportApiVersions = true;
}).AddApiExplorer(o =>
  o.GroupNameFormat = "'v'VVV");

Part 2: Version via URL, Header, or Query

// URL segment: /api/v1/orders
[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/orders")]

// Header: api-version: 2.0
// Query: ?api-version=2.0

[ApiVersion(2.0)]
[MapToApiVersion(2.0)]
public IActionResult GetV2() { }

Part 3: Deprecation Policy

// Mark version as deprecated
[ApiVersion(1.0, Deprecated = true)]

// Response headers automatically include:
// api-supported-versions: 2.0, 3.0
// api-deprecated-versions: 1.0
// sunset: Sat, 01 Jan 2027 00:00:00 GMT

Part 4: Sunset Dates & Communication

Follow RFC 8594 for Sunset headers:

Add sunset date 6+ months before removal
Document in OpenAPI with a deprecation note
Email registered API consumers
Return Warning: 299 header on deprecated endpoints