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?
answer
- Asp.Versioning.Http vs Asp.Versioning.Mvc
- AddApiVersioning returns IApiVersioningBuilder
- DefaultApiVersion 1.0, nothing assumed
- api-version query or URL segment
- 400 ApiVersionUnspecified
basics
~20 sAsp.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 sAPI 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 linesusing 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 controllersgo deeper
Recall the packages and the registration call, and that a missing version is a 400 unless you choose otherwise.
Explain each default on ApiVersioningOptions, which readers are active, and which problem codes the client gets for missing, unknown and malformed versions.
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.
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.