API Versioning with Asp.Versioning

Why version your API?

Once an API has consumers — mobile apps, third-party integrations, SPAs — every breaking change risks breaking them. Without versioning, you face an impossible choice: freeze the API forever or coordinate simultaneous upgrades across all clients.

URL-based versioning (/api/v1/, /api/v2/) makes the contract explicit and allows old and new versions to coexist. Consumers migrate on their own schedule. Granit.Http.ApiVersioning adds RFC 8594 deprecation headers (Sunset, Deprecation, Link) so clients receive advance notice of upcoming removals — no more surprise breakages.

Granit.Http.ApiVersioning configures Asp.Versioning with a URL segment primary reader (/api/v{version:apiVersion}/resource) and a query string fallback (?api-version=1.0).

Setup

[DependsOn(typeof(GranitHttpApiVersioningModule))]
public class AppModule : GranitModule { }

{
  "ApiVersioning": {
    "DefaultMajorVersion": 1,
    "ReportApiVersions": true
  }
}

Usage

var v1 = app.NewVersionedApi("Appointments").MapGroup("/api/v{version:apiVersion}");

var v1Group = v1.MapGroup("/appointments").HasApiVersion(1);
v1Group.MapGet("/", GetAppointments);
v1Group.MapPost("/", CreateAppointment);

var v2Group = v1.MapGroup("/appointments").HasApiVersion(2);
v2Group.MapGet("/", GetAppointmentsV2);

Deprecation headers (RFC 8594)

Mark endpoints as deprecated with automatic Deprecation, Sunset, and Link response headers:

v1Group.MapGet("/legacy-patients", GetLegacyPatients)
    .Deprecated(sunsetDate: "2026-06-01", link: "https://docs.example.com/migration/v2");

Response headers:

Deprecation: true
Sunset: Sun, 01 Jun 2026 00:00:00 GMT
Link: <https://docs.example.com/migration/v2>; rel="deprecation"

Each call to a deprecated endpoint is logged at Warning level.

Configuration reference

Property	Default	Description
`DefaultMajorVersion`	`1`	Default API version when client does not specify one
`ReportApiVersions`	`true`	Include `api-supported-versions` and `api-deprecated-versions` headers

Public API summary

Category	Key types	Package
Module	`GranitHttpApiVersioningModule`	—
Options	`GranitApiVersioningOptions`	`Granit.Http.ApiVersioning`
Attributes	`DeprecatedAttribute`	`Granit.Http.ApiVersioning`
Extensions	`AddGranitApiVersioning()`, `.Deprecated()`	`Granit.Http.ApiVersioning`