Versioning ASP.NET Core Web APIs with Microsoft.AspNetCore.Mvc.Versioning

Software teams building public-facing services eventually run into an awkward realisation: every useful API breaks someone, eventually. A field gets renamed, a payload shrinks, a long-standing date format suddenly needs to support ISO 8601 with offsets for European partners. The C# Corner Annual Conference 2020 has tracked this pattern across stacks for years, and several sessions are dedicated to the unglamorous craft of evolving interfaces without forcing every consumer to redeploy on the same afternoon.

For Australian developers specifically, the pressure to version well has intensified since the Consumer Data Right began mandating open banking endpoints at CBA, NAB, ANZ, and Westpac. Banks and fintechs in Sydney and Melbourne now publish versioned APIs the way postal services publish postcodes: predictably, visibly, and with a public deprecation calendar. The Microsoft.AspNetCore.Mvc.Versioning library has become the default .NET choice for this work, and what follows is a practical walkthrough of building a clean, production-grade implementation.

Why every public endpoint needs a versioning strategy

An API without versions is, in practice, an API that cannot change. The first release always feels permanent: contracts ship, mobile clients cache responses, partner integrations move through change boards, and Slack threads document implied commitments that nobody ever wrote down. Once a single breaking change becomes impossible, the codebase starts paying interest in workarounds, optional fields, and ad-hoc parsing rules that quietly rot the codebase.

Versioning resets that clock. By tagging routes with explicit version numbers, teams can introduce breaking changes behind a new segment while keeping legacy consumers running unchanged. This is the approach the Australian Prudential Regulation Authority expects from regulated entities under CPS 234, since every security improvement is technically a contract change and deserves its own release line.

The library, maintained by Chris Martinez and a small set of contributors, plugs into the standard ASP.NET Core middleware pipeline without requiring a custom serializer or a particular architectural style. It plays cleanly with the dependency injection container that ships in-box, which keeps the upgrade path short when teams migrate from .NET Core 3.1 to later .NET versions.

Setting up the library in a fresh project

Installation is a single package reference. From the Package Manager Console in Visual Studio, or directly in a CI pipeline running dotnet add package Microsoft.AspNetCore.Mvc.Versioning, the package resolves against .NET Core 3.1 and the newer .NET versions that sit on most Australian build servers. There are no native dependencies that require platform-specific tooling, which simplifies container builds targeting ap-southeast-2 or the newer Azure Australia regions.

Once referenced, registration happens in Startup.ConfigureServices. Calling AddApiVersioning returns a builder that exposes the four options that matter most: DefaultApiVersion, AssumeDefaultVersionWhenUnspecified, ReportApiVersions, and ApiVersionReader. The first sets the version returned when a caller forgets to ask. The second decides whether the framework honours that default or returns a 400. The third controls whether response headers advertise supported versions, which is critical for clients that discover capability at runtime. The fourth selects where the version string is read from on each request.

A minimal but reasonable configuration resembles:

services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(2, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

Controllers then opt in by decorating themselves with [ApiVersion] attributes, and the framework matches incoming requests against those declarations. Pairing this with AddVersionedApiExplorer() on the IMvcBuilder wires up the metadata needed for tooling like Swagger.

Choosing where versions live in the request

The version reader choice is partly stylistic and partly architectural. A header-driven strategy keeps URLs clean, which suits microservices behind an API gateway running in AWS Sydney. A URL-segment strategy, by contrast, makes versioned endpoints visible to anyone reading logs in Kibana, which is often what incident responders in Brisbane prefer at 2 a.m. AEST when something is on fire. The library supports four readers and they can be combined.

Query string, URL segment, header, and media type parameters can all be configured independently, and ApiVersionReader.Combine allows multiple readers to coexist. This matters for organisations that inherit older partners using query strings while onboarding new partners onto header-based discovery. The trade-offs between approaches are captured in the comparison below.

The combination approach tends to be what CDR-compliant banks settle on. Public endpoints use URL segments for human readability, while machine-to-machine flows rely on headers for tighter coupling with gateway policies. Picking a single reader is fine for a single product; combining two readers becomes essential once you have a mixed audience with different integration patterns.

Decorating controllers, surfacing deprecation, and documenting with Swagger

Real applications rarely have exactly two versions of exactly one controller. Some endpoints stay frozen forever, others carry parallel minor versions, and a few are explicitly retired but still reachable for a grace window. The library handles all of these through attribute composition on the controller class.

Applying [ApiVersion("1.0")] to a controller marks the entire surface as version 1.0. Adding a second attribute, [ApiVersion("2.0")], signals that the same controller also responds to that version, which lets older code migrate gradually without breaking in flight. For endpoints that are genuinely the same regardless of version, [ApiVersionNeutral] excludes them from the matching logic entirely; health checks and metadata endpoints usually take this path.

Deprecation deserves explicit handling. [Obsolete] on the .NET type is one signal, but the library ships its own [Deprecated] marker that propagates into response headers. The Sunset policy attaches a date the team can publish on their developer portal so partners see the retirement timeline months ahead. Australian teams working with myGov or ATO integrations often rely on this header to align their own maintenance windows with the ATO's quarterly release calendar.

When a single controller action needs to behave differently between versions, MapToApiVersion keeps the change local. Other overloads of the same action remain bound to their declared versions, which keeps the diff in code review readable and limits the blast radius of any review mistake. Documentation is the other half of the contract. Pairing the library with Swashbuckle.AspNetCore and injecting IApiVersionDescriptionProvider produces one OpenAPI document per version.

Regional considerations for Australian deployments

Cloud deployment choices influence versioning architecture more than they appear to. Azure Australia East and Australia Central 2 sit within Australian geographic boundaries, which is the expectation under the Privacy Act for any data touching citizens. Behind those regions, the versioned API surface is often fronted by Azure API Management, which understands versioning natively and can route /v1/ and /v2/ to different backend revisions without touching application code.

Time zone windows matter as well. Production deployments in Melbourne and Sydney tend to be scheduled for Sunday afternoon AEDT, partly because that aligns with low consumer traffic and partly because on-call rotations cycle Monday morning. Versioned APIs make those windows safer: the new version can sit behind a feature flag while the previous one continues serving real traffic, then get promoted once health metrics confirm stability over a few hours.

Compliance shapes the structure too. CDR-mandated data holders must publish public versions of their data sharing APIs with explicit deprecation timelines, and APRA-regulated entities track every change as a contract event under CPS 234. The Microsoft.AspNetCore.Mvc.Versioning library gives those teams the metadata they need, both in response headers and in generated OpenAPI descriptions, which keeps audit trails clean when assessors come knocking.

Practical recommendations for rolling out versioned APIs

• Adopt URL segments as the primary version reader and add a header reader as a secondary channel for service-to-service callers.
• Set ReportApiVersions = true on every public deployment so api-supported-versions and api-deprecated-versions headers are always emitted on responses.
• Reserve [ApiVersionNeutral] for health, metrics, and discovery endpoints that should never break clients during a migration.
• Use MapToApiVersion sparingly, preferring new controllers or partial class files for distinctly shaped versions to keep code review diffs clean.
• Generate one OpenAPI document per version and expose a version selector in Swagger UI so partners can switch context without leaving the page.
• Publish a deprecation calendar alongside the API reference, with sunset dates aligned to your maintenance window (a Sunday arvo AEDT slot works well for AU teams).
• Keep version numbers formatted as Major.Minor and avoid patch-style suffixes, since patch implies backwards-compatible behaviour that explicit versioning is designed to relax deliberately.