skip to content

Asp.Versioning Library

The Asp.Versioning packages version controllers and Minimal APIs through AddApiVersioning, [ApiVersion] and version sets. Interviewers check which reader picks the version and what the defaults do.

part ofASP.NET Coreread it →
on this pageshow

explore

questions

6

In ASP.NET Core, how do you add API versioning with the Asp.Versioning 10 packages, and what do its defaults do with an unversioned request?

level: juniorimportance: must knowfreq 55%

answer

  1. Asp.Versioning.Http vs Asp.Versioning.Mvc
  2. AddApiVersioning returns IApiVersioningBuilder
  3. DefaultApiVersion 1.0, nothing assumed
  4. api-version query or URL segment
  5. 400 ApiVersionUnspecified

basics

~20 s

Asp.Versioning.Http (Minimal APIs) or Asp.Versioning.Mvc (controllers, via .AddMvc()) plus services.AddApiVersioning(). By default versions come from the api-version query parameter or a URL segment, nothing is assumed, so a request to a versioned endpoint without a version gets 400.

solid answer

~40 s

API versioning is not built into ASP.NET Core; it comes from the `Asp.Versioning.*` packages, whose 10.x line targets only `net10.0`. `Asp.Versioning.Http` covers Minimal APIs, `Asp.Versioning.Mvc` adds controllers, and the API-explorer and `Asp.Versioning.OpenApi` packages feed documentation. `builder.Services.AddApiVersioning(...)` returns an `IApiVersioningBuilder` on which you chain `.AddMvc()`, `.AddApiExplorer()` or `.AddOpenApi()`. Defaults on `ApiVersioningOptions`: `DefaultApiVersion` is 1.0, `AssumeDefaultVersionWhenUnspecified` is false, `ReportApiVersions` is false, and the reader combines `QueryStringApiVersionReader` (`api-version`) with `UrlSegmentApiVersionReader`, so headers are ignored unless configured. A request to a versioned endpoint with no version therefore gets **400** with the `ApiVersionUnspecified` problem code; an unknown query-string version also gets 400 (`UnsupportedApiVersionStatusCode`), while a version in the URL path that nothing implements gets 404.

code

csharp · 12 lines
csharp
using Asp.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails();          // problem bodies for 400s
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;           // default false
    // DefaultApiVersion = 1.0, AssumeDefaultVersionWhenUnspecified = false
    // ApiVersionReader = query "api-version" + URL segment
})
.AddMvc();                                      // only if you use controllers

go deeper

for a junior

Recall the packages and the registration call, and that a missing version is a 400 unless you choose otherwise.

for a middle

Explain each default on ApiVersioningOptions, which readers are active, and which problem codes the client gets for missing, unknown and malformed versions.

for a senior

Decide which defaults to change for a real client base, such as adding a header reader or reporting versions, and make the error bodies useful with AddProblemDetails.

for a principal

Set a house standard for how every service reads, reports and rejects versions, so clients meet the same behaviour across the estate.

## Where versioning comes from ASP.NET Core has no versioning API of its own. The **Asp.Versioning** libraries add it, and the 10.x packages target only `net10.0`. | Package | Adds | |---|---| | `Asp.Versioning.Http` | the core: options, readers, Minimal API version sets | | `Asp.Versioning.Mvc` | controller support (`[ApiVersion]`, `[MapToApiVersion]`) | | `Asp.Versioning.Mvc.ApiExplorer` | one API description group per version, for documentation | | `Asp.Versioning.OpenApi` | integration with `Microsoft.AspNetCore.OpenApi`, new in 10 | | `Asp.Versioning.Grpc`, `Asp.Versioning.OData` | the same model for gRPC services and OData | Registration is one call that returns a builder: - `builder.Services.AddApiVersioning(options => ...)` registers the services and returns `IApiVersioningBuilder`. - `.AddMvc()` turns on controller versioning; without it, controllers are not versioned. - `.AddApiExplorer(...)` and `.AddOpenApi(...)` describe each version for documentation. ## The defaults `ApiVersioningOptions` starts like this in 10.2: | Option | Default | Meaning | |---|---|---| | `DefaultApiVersion` | `ApiVersion.Default`, which is 1.0 | the version a selector falls back to | | `AssumeDefaultVersionWhenUnspecified` | `false` | a missing version is an error, not 1.0 | | `ApiVersionReader` | query string `api-version` combined with URL segment | where the version is read from | | `ReportApiVersions` | `false` | no `api-supported-versions` headers | | `UnsupportedApiVersionStatusCode` | 400 | status for a version no endpoint implements; a version read from the URL path gets 404 instead | | `RouteConstraintName` | `apiVersion` | the constraint used in `v{version:apiVersion}` | Two consequences surprise people: 1. **Headers are not read by default.** A client sending `api-version: 2.0` as a header is treated as unversioned until you configure `HeaderApiVersionReader`. 2. **No version is not the same as 1.0.** With `AssumeDefaultVersionWhenUnspecified` false, a request that reaches only versioned endpoints and carries no version is answered by a client-error endpoint with **400**. ## What the client sees For the loyalty-points API, where `GET /points` is declared for 1.0 and 2.0: - `GET /points?api-version=2.0` reaches the 2.0 handler. - `GET /points` returns 400 with the problem code `ApiVersionUnspecified`. - `GET /points?api-version=3.0` returns 400, `UnsupportedApiVersion`; change `UnsupportedApiVersionStatusCode` if you prefer another status. - `GET /points?api-version=two` returns 400, `InvalidApiVersion`. The errors are written as problem details, with the code in a `code` extension member, only when an `IProblemDetailsService` is registered, which is why the library's examples call `builder.Services.AddProblemDetails()`; without it the status code comes back with an empty body. Endpoints that never opted into versioning are unaffected: an unversioned endpoint still matches normally. ## Reading the version in code A handler or action can declare an `ApiVersion` parameter and receive the requested version. Elsewhere, `HttpContext.RequestedApiVersion` (an extension property in 10) returns it, or null when no version was sent or it could not be parsed. ## Choosing what to change - Add `HeaderApiVersionReader` or `MediaTypeApiVersionReader` with `ApiVersionReader.Combine(...)` when clients send versions that way. - Turn on `ReportApiVersions` so clients can discover supported and deprecated versions. - Set `AssumeDefaultVersionWhenUnspecified` only as a migration aid for clients that predate versioning. Which of URL, query, header or media type is the right strategy for an API is a protocol-design question; this library only implements whichever you pick. ## Registration mistakes interviewers probe 1. **Controllers without `.AddMvc()`.** `AddApiVersioning()` alone versions Minimal APIs; controllers keep routing as if they declared no version. Asp.Versioning 10 ships analyzer **AV0013** ("Missing AddMvc") for exactly this. 2. **Expecting a header to work out of the box.** Nothing reads headers until a `HeaderApiVersionReader` with a header name is configured. 3. **Treating the 400 as a routing bug.** A 400 whose `code` is `ApiVersionUnspecified`, `InvalidApiVersion` or `UnsupportedApiVersion` comes from the versioning matcher policy, not from model binding or the route table. 4. **Forgetting `AddProblemDetails()`.** The client gets the right status with an empty body and no `code` to act on.

  • Why does a client sending the version in an api-version header get 400 ApiVersionUnspecified?
    The default `ApiVersionReader` combines only `QueryStringApiVersionReader` and `UrlSegmentApiVersionReader`; headers are never read unless you add `HeaderApiVersionReader` with the header name, usually through `ApiVersionReader.Combine(...)`. Until then the request counts as unversioned, and with `AssumeDefaultVersionWhenUnspecified` false that is a 400.
  • Why does the 400 come back with an empty body in one app and a JSON problem in another?
    Asp.Versioning's client-error endpoints write a problem-details body only through `IProblemDetailsService`. Call `builder.Services.AddProblemDetails()` and the 400 carries a problem object with type, title and detail, such as the `ApiVersionUnspecified` code; without it only the status code is set.

  • API versioning is built into ASP.NET Core 10; no package is needed.
  • By default Asp.Versioning reads the version from an api-version request header.
  • A request with no version is treated as 1.0 by default.
  • An unknown api-version value returns 404 by default.
  • AddApiVersioning() alone versions controllers; AddMvc() is only for views.

Assumes Asp.Versioning 10.2 on ASP.NET Core 10: the packages target net10.0 only and the defaults are read from ApiVersioningOptions at that version.

open as a page

With Asp.Versioning 10 Minimal APIs, how do you run v1 and v2 of a loyalty-points API side by side with NewVersionedApi or NewApiVersionSet?

level: middleimportance: must knowfreq 50%

basics

~20 s

Call app.NewVersionedApi("Loyalty"), map one group per version with HasApiVersion(1.0) and HasApiVersion(2.0), or build an ApiVersionSet with NewApiVersionSet() and attach it with WithApiVersionSet plus MapToApiVersion. Each request is routed to the handler for its requested version.

open as a page

When moving loyalty-points clients from v1 to v2 with Asp.Versioning 10, what do AssumeDefaultVersionWhenUnspecified, the version selector, ReportApiVersions and sunset policies each do?

level: middleimportance: should knowfreq 40%

basics

~10 s

AssumeDefaultVersionWhenUnspecified lets unversioned requests through by asking the ApiVersionSelector for a version, 1.0 with the default selector. ReportApiVersions adds api-supported-versions and api-deprecated-versions headers, and options.Policies.Sunset or Deprecate adds dated policy headers for a version.

open as a page

In an ASP.NET Core controller versioned with Asp.Versioning 10, what do [ApiVersion], [MapToApiVersion] and [ApiVersionNeutral] do, and how do two actions share one route?

level: middleimportance: should knowfreq 45%

basics

~20 s

[ApiVersion] on a controller declares the versions it implements, [MapToApiVersion] on an action narrows that action to one of them, and [ApiVersionNeutral] opts a controller or action out. Two actions on one route split versions this way; it needs AddApiVersioning().AddMvc().

open as a page

In ASP.NET Core 10 with Asp.Versioning, how do you publish one OpenAPI document per API version for the built-in Microsoft.AspNetCore.OpenApi generator?

level: seniorimportance: should knowfreq 30%

basics

~10 s

Add Asp.Versioning.OpenApi, chain .AddApiExplorer(o => o.GroupNameFormat = "'v'VVV") and .AddOpenApi() on AddApiVersioning, then call app.MapOpenApi().WithDocumentPerVersion(). Each version gets its own document, such as /openapi/v1.json and /openapi/v2.json.

open as a page

With Asp.Versioning 10, how do you accept the version from a header or media type, and what happens when a request carries two conflicting versions?

level: seniorimportance: should knowfreq 35%

basics

~10 s

Set ApiVersioningOptions.ApiVersionReader to ApiVersionReader.Combine(...) with a HeaderApiVersionReader naming the header and, if wanted, a MediaTypeApiVersionReader for the v parameter. If the readers return two different version strings, the request gets 400 AmbiguousApiVersion.

open as a page