Why Version APIs
API versioning exists because a service's contract inevitably needs to evolve, renamed fields, restructured responses, changed behavior, while existing clients keep calling the API exactly as they always have. Rather than mutating a live endpoint's contract in place and breaking every integration built against it, versioning isolates breaking changes into a new version, like v2, so v1 continues honoring its original contract for as long as it's supported.
Cricket analogy: Versioning an API is like the ICC introducing new playing regulations, say a change to powerplay overs, only from a specific season onward rather than retroactively rewriting history for a match played last year: v2 of an endpoint can change behavior while v1 keeps honoring the contract existing clients already integrated against.
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
}).AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
});
var app = builder.Build();
var versionSet = app.NewApiVersionSet()
.HasApiVersion(new ApiVersion(1, 0))
.HasApiVersion(new ApiVersion(2, 0))
.ReportApiVersions()
.Build();
app.MapGroup("/api/v{version:apiVersion}/products")
.WithApiVersionSet(versionSet)
.MapGet("/{id:int}", (int id) => Results.Ok(new { id, name = "Widget" }))
.HasApiVersion(new ApiVersion(1, 0));Versioning Strategies
Common versioning strategies include URL segment versioning (/api/v2/products), which is highly visible and cache-friendly but couples the version into every route; query string versioning (?api-version=2.0), which keeps the base URL stable; header versioning, using a custom header like X-Api-Version; and media type versioning, negotiated through the Accept header, such as application/vnd.company.v2+json, which follows REST's content-negotiation philosophy most closely.
Cricket analogy: URL segment versioning like /api/v2/players is like a cricket ground having entirely separate turnstiles labeled 'Members' and 'General': the version is baked right into the entry point, unmistakable before you even reach the gate, unlike header versioning which is like showing a badge only once you're inside.
The Asp.Versioning.Mvc package (the actively maintained successor to Microsoft.AspNetCore.Mvc.Versioning) exposes [ApiVersion("2.0")] on a controller or action, plus [MapToApiVersion] when multiple versions share one controller. Combined with AddApiExplorer, it can also generate a distinct Swagger document per version automatically.
Versioning Minimal APIs
Minimal APIs support versioning through the same underlying Asp.Versioning packages, but the API surface differs from attributes: builder.NewApiVersionSet() declares which versions are supported and returns a builder you configure with .HasApiVersion(), and calling .Build() produces an ApiVersionSet that's attached to a MapGroup via .WithApiVersionSet(), applying that version configuration to every route registered within the group at once.
Cricket analogy: Defining an ApiVersionSet with builder.NewApiVersionSet().HasApiVersion(2.0) is like a tournament committee formally registering which rule revisions apply to a specific edition of a league before a ball is bowled: MapGroup("/api/v{version:apiVersion}/players").WithApiVersionSet(versionSet) then applies that registered rule set to every route in the group.
Deprecation and Sunset Policies
Deprecation should be communicated well before a version is actually removed. Marking an ApiVersion as .Deprecated() surfaces it in the api-supported-versions response metadata without removing functionality, while a Sunset HTTP header carries a concrete, machine-readable retirement date, letting client tooling detect and warn about the impending change automatically rather than relying on developers reading a changelog.
Cricket analogy: Marking an API version Deprecated is like the ICC announcing that a specific bat-sensor technology will no longer be legal starting next season, giving players a grace period to switch: .Deprecated() on an ApiVersion tells clients through response metadata that v1 still works today but shouldn't be relied on for new integrations.
Shipping a breaking change (renaming a field, changing a status code, altering pagination behavior) into an existing API version without bumping the version number silently breaks every client already integrated against that version's contract. Treat any change that isn't purely additive as a reason to introduce a new version rather than mutating the old one in place.
- API versioning preserves an existing consumer contract while letting the API evolve through a new version for new clients.
- Common strategies include URL segment versioning, query string versioning, header versioning, and media type versioning.
- The Asp.Versioning.Mvc package provides [ApiVersion] and [MapToApiVersion] attributes for controller-based APIs.
- Minimal APIs version routes through NewApiVersionSet() and WithApiVersionSet() applied to a MapGroup.
- Marking a version .Deprecated() and returning a Sunset header gives consumers a concrete, machine-readable migration deadline.
- Any change that isn't purely additive, renamed fields, altered status codes, changed pagination, warrants a new version rather than mutating an existing one.
Practice what you learned
1. What is the primary purpose of API versioning?
2. Which versioning strategy embeds the version directly in the URL path, like /api/v2/products?
3. In minimal APIs, how do you associate a group of routes with a specific set of supported API versions?
4. What does marking an API version as .Deprecated() accomplish?
5. Which of these changes to an existing, live API version would generally require a new version rather than being safely additive?
Was this page helpful?
You May Also Like
Controllers and Attribute Routing
How ControllerBase classes and [Route]/[Http*] attributes map incoming requests to action methods in ASP.NET Core Web API.
Minimal APIs
A lightweight, low-ceremony way to build HTTP APIs in ASP.NET Core using top-level route handlers instead of controller classes.
Action Results and Status Codes
How ASP.NET Core action results map to HTTP status codes, and how to choose the right response for every outcome.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics