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?
answer
- NewVersionedApi returns a route-group builder
- HasApiVersion on a group
- MapToApiVersion picks one version
- IsApiVersionNeutral for health or ping
- ApiVersion as a handler parameter
basics
~20 sCall 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.
solid answer
~40 sMinimal APIs declare versions as endpoint metadata. The current style is `var loyalty = app.NewVersionedApi("Loyalty");`, which creates a route group, then one group per version: `loyalty.MapGroup("/api/v{version:apiVersion}/points").HasApiVersion(1.0)` and another with `HasApiVersion(2.0)`. Each group maps its own `GET /{memberId}`, so v1 returns a plain balance and v2 adds tier and expiring points, side by side. The older style builds an `ApiVersionSet` with `app.NewApiVersionSet().HasApiVersion(1.0).HasApiVersion(2.0).Build()`, attaches it with `WithApiVersionSet(set)`, and pins handlers with `MapToApiVersion(1.0)`; an endpoint in a set without `MapToApiVersion` serves every version in the set. `IsApiVersionNeutral()` keeps endpoints such as a ping out of versioning, `HasDeprecatedApiVersion` marks an old version, and a handler can take an `ApiVersion` parameter to read the requested version.
code
csharp · 15 linesvar loyalty = app.NewVersionedApi("Loyalty");
var v1 = loyalty.MapGroup("/api/v{version:apiVersion}/points")
.HasDeprecatedApiVersion(1.0);
v1.MapGet("/{memberId}", (string memberId, IPointsLedger ledger) =>
ledger.Balance(memberId)); // int
var v2 = loyalty.MapGroup("/api/v{version:apiVersion}/points")
.HasApiVersion(2.0);
v2.MapGet("/{memberId}", (string memberId, IPointsLedger ledger, ApiVersion version) =>
new PointsSummary(ledger.Balance(memberId),
ledger.Tier(memberId),
ledger.ExpiringSoon(memberId)));
app.MapGet("/ping", () => "pong").IsApiVersionNeutral();go deeper
Recall the two styles, versioned route groups and version sets, and that HasApiVersion declares while MapToApiVersion narrows.
Explain how the matcher chooses between two endpoints on the same route, what an unmapped endpoint in a set serves, and how neutral endpoints behave.
Lay out a v1 and v2 side by side so v1 stays frozen: separate groups or handlers, deprecated marking, and neutral infrastructure endpoints.
Decide how long two versions run in parallel and how the code layout keeps the cost of each extra version visible.
## Versions are endpoint metadata In Minimal APIs, Asp.Versioning works by attaching version metadata to endpoints and adding a matcher policy that picks, among endpoints with the same route, the one whose versions include the requested version. Nothing else changes: handlers, filters and results are ordinary Minimal API code. ## NewVersionedApi: one API, groups per version `app.NewVersionedApi("Loyalty")` creates an empty-prefix route group for one logical API and returns an `IVersionedEndpointRouteBuilder`. The optional name is added as a tag. You then create groups that declare versions: - `loyalty.MapGroup("/api/v{version:apiVersion}/points").HasApiVersion(1.0)` declares that every endpoint in the group implements 1.0. - A second group with `HasApiVersion(2.0)` holds the 2.0 handlers. - `HasDeprecatedApiVersion(1.0)` declares a version that still works but is reported as deprecated. - `MapToApiVersion(2.0)` on an endpoint inside a group that declares several versions maps that endpoint to one of them. The library forbids calling `NewVersionedApi` on a nested group; it is meant to be the root of one API. ## NewApiVersionSet: the older style Before versioned route groups, endpoints shared a **version set**: 1. `var points = app.NewApiVersionSet("Loyalty").HasApiVersion(1.0).HasApiVersion(2.0).ReportApiVersions().Build();` 2. `app.MapGet("/points/{memberId}", ...).WithApiVersionSet(points).MapToApiVersion(1.0);` 3. `app.MapGet("/points/{memberId}", ...).WithApiVersionSet(points).MapToApiVersion(2.0);` An endpoint in a set with no `MapToApiVersion` call implements every version of the set. Both styles are supported in 10; groups read better when versions diverge in many endpoints. ## Comparing the calls | Call | Applies to | Effect | |---|---|---| | `HasApiVersion(2.0)` | group or endpoint | declares 2.0 as implemented | | `HasDeprecatedApiVersion(1.0)` | group or endpoint | implemented, reported as deprecated | | `MapToApiVersion(2.0)` | endpoint | narrows the endpoint to one declared version | | `AdvertisesApiVersion(3.0)` | group or endpoint | reports a version implemented elsewhere | | `IsApiVersionNeutral()` | endpoint | matches any version, or none | | `ReportApiVersions()` | set or endpoint | adds version headers for this API only | ## Reading the version inside a handler A handler can declare an `ApiVersion` parameter, as in `(string memberId, ApiVersion version) => ...`, and the library supplies the requested version. In shared helper code, `httpContext.RequestedApiVersion` returns the same value, or null when the request carried no parseable version. Branching on the version inside one handler works, but separate handlers per version keep v1 frozen while v2 evolves. ## How the URL segment fits in The `{version:apiVersion}` segment uses the `apiVersion` route constraint that Asp.Versioning registers. With the default reader, both `/api/v2/points/42` and `/points/42?api-version=2.0` styles are understood, but a group whose prefix contains the segment can only be reached with it: `/api/points/42` does not match that route at all. ## Keeping some endpoints out Health probes, a `/ping` or an OAuth callback should not demand a version. Mark them with `IsApiVersionNeutral()`, or simply map them outside the versioned API: endpoints with no version metadata are not subject to version matching. ## Groups or sets: how to choose | Concern | Versioned route groups | Version set | |---|---|---| | Versions declared on | each `MapGroup(...)` | one `ApiVersionSet` object | | Per-endpoint call | none, the group carries it | `WithApiVersionSet(set)` on every endpoint | | Splitting handlers | one group per version | `MapToApiVersion` per endpoint | | Reporting | `ReportApiVersions()` on the group or endpoint | `.ReportApiVersions()` on the set builder | Groups keep each version's endpoints together in code, which makes it obvious what v2 changed. A set suits a small API where most endpoints serve every version and only one or two diverge.
- What does an endpoint in a version set serve if you never call MapToApiVersion on it?It implements every version declared on the set, so with a set of 1.0 and 2.0 it answers both. `MapToApiVersion` narrows an endpoint to one declared version; that is how two handlers on the same route split the versions between them.
- Why does GET /api/points/42 return 404 while GET /api/v1/points/42 works?The group's prefix contains the `{version:apiVersion}` segment, so the route template itself requires it. A path without the segment matches no route, which is a plain routing 404 before versioning runs. Clients of URL-segment routes must always send the segment.
- MapToApiVersion declares a new version even if the set or group never declared it.
- An endpoint in a version set without MapToApiVersion serves only the first version.
- IsApiVersionNeutral() means the endpoint only answers requests with no version.
- Minimal API versioning needs AddMvc() on the versioning builder.
- A Minimal API handler cannot see which version was requested.
Assumes Asp.Versioning 10.2 on ASP.NET Core 10; NewVersionedApi, version sets and the HttpContext.RequestedApiVersion extension property are read from that release.