Feature request: declarative attribute for endpoints introduced in a specific API version

[xavierjohn]

Feature request: declarative attribute for endpoints introduced in a specific API version

Summary

Add a first-class attribute to declare that an endpoint was introduced in a specific API version, so requests under prior versions return a clear 404 (or other configured status) without per-endpoint stub actions or global side-effects.

Working name suggestion: [IntroducedInApiVersion("...")]. Naming open to discussion.

Motivation

Evolving an API across multiple versions is a common scenario: ship 2026-11-12 with N endpoints, then ship 2026-12-01 with the same N endpoints plus a new one — say POST /api/orders/{id}/return — that should only be reachable under v2.

The behaviour the framework exposes today is:

• GET /api/orders/{id}/return?api-version=2026-12-01 → routes to the v2 action ✅
• GET /api/orders/{id}/return?api-version=2026-11-12 → returns 400 Unsupported API version ⚠️

The 400 is technically correct (the combination of route + version is unsupported), but in practice clients on v1 are calling a route that doesn't exist for them, which is a 404-shaped concern. RFC 9110 §15.5.5 maps "the origin server did not find a current representation for the target resource" to 404; "version doesn't exist" maps to 400. Today the framework cannot distinguish.

Distinguishing matters in practice because:

1. Clients monitor 4xx rates by status code; 404s trigger different alerts than 400s.
2. v1 clients should be able to safely probe routes (e.g., a feature-detection script) and infer "the operation is not available on my version" from the status without parsing a 400 body.
3. For routes that truly don't exist on any version (typo'd path) the same 400 fires today, conflating two real client bugs.

Current workarounds

There are two ways to solve this today, and both have downsides.

A. Global UnsupportedApiVersionStatusCode = 404

services.AddApiVersioning(options =>
{
    options.UnsupportedApiVersionStatusCode = StatusCodes.Status404NotFound;
});

This makes the 400 in the example above a 404 — but it also turns every unsupported-version response into a 404, including a request like ?api-version=2025-99-99 against a route that exists in current versions. That request is "I sent a version you don't recognise", which is more naturally a 400. The global flag conflates the two semantics.

B. Per-endpoint stub action returning 404

Add an action with the same path on the v1 controller that explicitly returns 404:

namespace MyService.v2026_11_12.Controllers;

[ApiController]
[Route("api/[controller]")]
public sealed class OrdersController : ControllerBase
{
    /// <summary>
    /// Stub for the v2-only POST /api/orders/{id}/return endpoint. v1 clients hitting
    /// this path get a clean 404 instead of the framework default 400. The Consumes list
    /// enumerates content types because [Consumes("application/json")] at the controller
    /// level would otherwise produce 415 (Unsupported Media Type) before the action runs
    /// for any client that sends a non-JSON content type or no body.
    /// </summary>
    [HttpPost("{id}/return")]
    [Consumes("application/json", "application/*+json", "text/json", "text/plain", "application/octet-stream")]
    [ApiExplorerSettings(IgnoreApi = true)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult ReturnNotFoundOnV1(string id) => NotFound();

    // ... v1's actual 11 endpoints below ...
}

This works, but the ceremony is significant per v2-only endpoint:

1. Hand-write a stub action that does nothing useful.
2. Enumerate plausible content types in [Consumes] to prevent the framework's [Consumes("application/json")]-driven 415 short-circuit before the action runs (e.g., when a probing client sends Content-Type: application/octet-stream, no Content-Type at all, or text/plain).
3. Add [ApiExplorerSettings(IgnoreApi = true)] to keep the stub out of the v1 OpenAPI / Swagger surface.
4. Repeat for every v2-only endpoint.
5. Keep the stubs in sync with the v2 controller as endpoints are added or removed — no compile-time guarantee.

For a service with three v2-only endpoints, this is ~50 lines of boilerplate that only converts a 400 into a 404. The boilerplate has to be maintained alongside the v2 controller indefinitely.

Proposed solution

A new attribute that declares an endpoint as "introduced in version X":

namespace MyService.v2026_12_01.Controllers;

[ApiController]
[Route("api/[controller]")]
public sealed class OrdersController : ControllerBase
{
    [HttpPost("{id}/return"), IntroducedInApiVersion("2026-12-01")]
    public Task<ActionResult<OrderResponse>> Return(string id, [FromBody] ReturnRequest request)
    {
        // Real implementation. No stub on the v1 controller required.
    }
}

The framework then handles three concerns automatically:

1. Routing-time gate. Requests to this endpoint under api-versions earlier than the declared SinceVersion return the configured status code (default 404).
2. API Explorer filtering. The action is hidden from the API Explorer (and therefore the OpenAPI / Swagger doc) for prior api-versions. Clients reading v1's swagger don't see the endpoint at all.
3. Allow header on 405 is unaffected. When a route is shared between a v1 stub and a v2 real action via path, the existing 405-vs-404 behaviour stays consistent.

Proposed signature

[AttributeUsage(
    AttributeTargets.Method | AttributeTargets.Class,
    AllowMultiple = false,
    Inherited = false)]
public sealed class IntroducedInApiVersionAttribute : Attribute
{
    public IntroducedInApiVersionAttribute(string sinceVersion);
    public IntroducedInApiVersionAttribute(int major, int minor);
    public IntroducedInApiVersionAttribute(int year, int month, int day);

    public ApiVersion SinceVersion { get; }

    /// <summary>
    /// Status code returned for requests under api-versions earlier than
    /// <see cref="SinceVersion"/>. Defaults to 404 (the endpoint did not
    /// exist in the requested version). 410 (Gone) is a reasonable
    /// alternative for endpoints that explicitly want to signal removal.
    /// </summary>
    public int LegacyResponseStatusCode { get; init; } = StatusCodes.Status404NotFound;
}

Usage examples

// Default: 404 for prior versions
[HttpPost("{id}/return"), IntroducedInApiVersion("2026-12-01")]
public Task<ActionResult<OrderResponse>> Return(...) => ...;

// Custom: 410 Gone (paired with a Sunset header in the legacy version)
[HttpPost("legacy-feature"), IntroducedInApiVersion("2.0", LegacyResponseStatusCode = StatusCodes.Status410Gone)]
public Task<ActionResult> LegacyFeature(...) => ...;

// At controller level — every action inherits unless overridden
[ApiController, IntroducedInApiVersion("2026-12-01"), Route("api/[controller]")]
public sealed class WidgetsController : ControllerBase
{
    // every action in this controller is v2+ only
}

Interaction with existing primitives

Existing	Interaction
[ApiVersion("X")]	Orthogonal. [ApiVersion] declares which versions an endpoint supports; [IntroducedInApiVersion] declares the minimum. A v2+ endpoint that supports v2, v3, v4 still uses [ApiVersion] × 3 for the supported set.
[MapToApiVersion("Y")]	Unchanged. The new attribute is a routing-time gate, not an action-version mapping.
[ApiVersionNeutral]	Incompatible. A neutral endpoint has no version concept. Should fail at startup with a clear MisconfiguredApiVersionException if both are present.
VersionByNamespaceConvention	Composes cleanly. The convention determines which versions an action supports; [IntroducedInApiVersion] filters by minimum.
URL-segment versioning (/v{version:apiVersion}/...)	Same routing-time gate. No special-casing needed.
UnsupportedApiVersionStatusCode global	Becomes per-endpoint-overridable. The global remains the default for "version doesn't exist at all"; the attribute overrides for "endpoint doesn't exist in this version".

Backward compatibility

The attribute is additive. Existing applications that don't use it are unaffected. Applications using the per-endpoint stub workaround can migrate one endpoint at a time — replacing the ReturnNotFoundOnV1 stub with [IntroducedInApiVersion] on the v2 action, then deleting the v1 stub.

Open design questions

1. Naming. [IntroducedInApiVersion] reads naturally next to [ApiVersion] and [MapToApiVersion]. Alternatives: [VersionedSince("X")], [ApiVersionAddedIn("X")], [FromApiVersion("X")]. Maintainer preference very welcome.

2. Default status code. 404 matches the natural "endpoint doesn't exist yet" semantics. 410 Gone would be misleading as a default. Keeping 404 as the default and allowing override seems right.

3. AllowMultiple = false vs true. My instinct is false — anything more nuanced ("introduced, then deprecated, then re-introduced") should compose with the existing [ApiVersion] / Deprecated = true machinery, not stack [IntroducedInApiVersion] × N.

4. Sunset / Deprecation header integration. Out of scope for this proposal, but a follow-up could emit Sunset / Deprecation headers on requests to a deprecated version. Mentioning here so the design doesn't accidentally close that door.

5. Class-level inheritance. Should [IntroducedInApiVersion] at the controller level apply to every action, or only those without an action-level override? Mirroring [ApiVersion]'s Inherited = false semantics seems consistent.

Why this belongs upstream

The behaviour is a pure routing-time check based on RequestedApiVersion against a declared minimum, plus an API Explorer filter. Both mechanisms already exist in Asp.Versioning; the missing piece is the declarative attribute that ties them together.

A downstream library cannot implement this cleanly because the routing-time dispatch and API Explorer filtering are framework-internal concerns. The current workarounds rely on the consumer reaching past the framework boundary (writing stub actions, hand-managing [ApiExplorerSettings], enumerating [Consumes] content types). Promoting it to a first-class attribute would prevent every consumer who ships an additive v2 from re-discovering and re-implementing the same workaround.

Implementation sketch

I'd be happy to contribute the implementation if there's interest. Rough plan:

• Add IntroducedInApiVersionAttribute to Asp.Versioning.Abstractions (alongside ApiVersionAttribute, MapToApiVersionAttribute).
• Hook into ApiVersionMatcherPolicy (or equivalent endpoint-selector pipeline) to short-circuit with the configured status code when RequestedApiVersion < SinceVersion.
• Hook into ApiVersionDescriptionProvider to filter ApiDescription entries for the prior-version ApiVersionDescription group.
• Tests: routing dispatch matrix (404 / 410 / 400), API Explorer surface check across two versions, interaction with [ApiVersion] + [MapToApiVersion] + namespace convention.

Want to align on the attribute name and signature first before I open a PR — happy to iterate based on maintainer guidance.

Thanks!

[xavierjohn]

Follow-up: full controller comparison + the semantic distinction this targets

Adding a fuller code example to make the proposal concrete, plus a clarification that came up while writing the example: what does the framework do today if a v2-only action just uses [MapToApiVersion("2026-12-01")] and no other workaround?

The answer turns out to be the headline motivation for this proposal, so I want to make it explicit.

Scenario

A single OrdersController ships under both 2026-11-12 and 2026-12-01. Most endpoints are shared. One endpoint — POST /api/orders/{id}/return — is new in 2026-12-01. v1 clients who call it should get a clear 404; the operation didn't exist in their version.

What the controller looks like today

[ApiController]
[ApiVersion("2026-11-12")]
[ApiVersion("2026-12-01")]
[Route("api/[controller]")]
[Produces(MediaTypeNames.Application.Json)]
public sealed class OrdersController : ControllerBase
{
    private readonly IOrderService _orders;
    public OrdersController(IOrderService orders) => _orders = orders;

    // ---- Shared lifecycle endpoints (CreateDraft, GetById, Submit, Approve,
    //      Ship, Deliver, Cancel) — abbreviated for readability ----

    // ---- New in v2 ----
    [HttpPost("{id:int}/return"), MapToApiVersion("2026-12-01")]
    [ProducesResponseType(typeof(OrderResponse), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
    public Task<ActionResult<OrderResponse>> Return(
        int id,
        [FromBody] ReturnOrderRequest request,
        CancellationToken cancellationToken)
        => _orders.ReturnAsync(id, request.Reason, cancellationToken);

    // ---- v1 stub workaround ----
    /// <summary>
    /// v1 stub for the v2-only POST /api/orders/{id}/return endpoint.
    /// Returns 404 for v1 clients hitting this path, instead of the framework's
    /// default 400. Two pieces of ceremony are required:
    ///
    /// 1. [MapToApiVersion("2026-11-12")] — bind the stub to v1.
    /// 2. [ApiExplorerSettings(IgnoreApi = true)] — keep the stub out of v1's
    ///    OpenAPI doc so v1 swagger doesn't advertise an endpoint v1 can't use.
    /// </summary>
    [HttpPost("{id:int}/return"), MapToApiVersion("2026-11-12")]
    [ApiExplorerSettings(IgnoreApi = true)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult ReturnNotFoundOnV1(int id) => NotFound();
}

What it would look like with the proposed attribute

[ApiController]
[ApiVersion("2026-11-12")]
[ApiVersion("2026-12-01")]
[Route("api/[controller]")]
[Produces(MediaTypeNames.Application.Json)]
public sealed class OrdersController : ControllerBase
{
    private readonly IOrderService _orders;
    public OrdersController(IOrderService orders) => _orders = orders;

    // ---- Shared lifecycle endpoints (same as above) ----

    // ---- New in v2 ----
    /// <summary>
    /// Return a delivered order within the 30-day return window.
    /// </summary>
    /// <remarks>
    /// New in API <c>2026-12-01</c>. Requests under <c>?api-version=2026-11-12</c>
    /// return <c>404 Not Found</c> automatically — the operation did not exist in
    /// the prior version. The action is also hidden from the <c>2026-11-12</c>
    /// OpenAPI document so v1 clients reading their swagger never see it.
    /// </remarks>
    [HttpPost("{id:int}/return")]
    [IntroducedInApiVersion("2026-12-01")]
    [ProducesResponseType(typeof(OrderResponse), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
    public Task<ActionResult<OrderResponse>> Return(
        int id,
        [FromBody] ReturnOrderRequest request,
        CancellationToken cancellationToken)
        => _orders.ReturnAsync(id, request.Reason, cancellationToken);
}

The diff is one stub action removed (route + MapToApiVersion + ApiExplorerSettings + NotFound body) and one attribute added on the real action.

What if I just used [MapToApiVersion("2026-12-01")] without the stub?

This is the obvious thing to try first, and worth covering because the answer is the headline motivation for the proposal.

For POST /api/orders/42/return?api-version=2026-11-12 against the v2-only action with no v1 stub, the framework returns:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://docs.api-versioning.org/problems#unsupported",
  "title": "Unsupported API version",
  "status": 400,
  "detail": "The HTTP resource that matches the request URI 'http://localhost/api/orders/42/return' does not support the API version '2026-11-12'.",
  "code": "UnsupportedApiVersion"
}

(Captured from a runnable reproducer — see attachment / test results below.)

The default 400 conflates two semantically different cases:

Request	What's actually true	RFC 9110 status	Framework today
?api-version=2026-11-12 against POST /api/orders/42/return	The endpoint genuinely doesn't exist in v1	404 Not Found (no current representation for the target resource)	400
?api-version=2025-99-99 against POST /api/orders/42 (any known path)	The requested version is unknown to the server	400 Bad Request (malformed request)	400

The framework can't tell them apart because the routing-time check is "does any candidate endpoint match this version?" — both cases produce a single boolean (no), and the same response.

Today's three options to fix it

Option	Effect	Trade-off
Live with 400	No code change	Clients can't bucket "operation doesn't exist on my version" by status; have to parse detail. Monitoring alerts mix two real client bugs.
Global UnsupportedApiVersionStatusCode = 404	All unsupported-version responses become 404	Fixes case #1 but breaks case #2 — ?api-version=2025-99-99 is now 404, which is misleading (the version genuinely doesn't exist server-side).
Per-endpoint v1 stub (BEFORE example above)	Both cases correct	A duplicate route + [MapToApiVersion] + [ApiExplorerSettings(IgnoreApi = true)] + NotFound body per v2-only endpoint. Has to be kept aligned with the real v2 action manually, and multiplies linearly as more v2-only endpoints are added.

[IntroducedInApiVersion] is the missing fourth option — declare at the action level that requests under prior versions return 404 (or 410, or whatever the team configures), without changing the global UnsupportedApiVersionStatusCode. The framework owns the routing-time gate AND the API Explorer filtering. Both semantic cases stay distinct.

Request	With [IntroducedInApiVersion("2026-12-01")]
?api-version=2026-11-12 against POST /api/orders/42/return	404 — per-endpoint, declarative
?api-version=2025-99-99 against any path	400 — global default unchanged

Summary

The proposal isn't just about saving boilerplate. It's about giving the framework a way to express the semantic distinction between "the endpoint didn't exist yet" (a routing concern) and "I don't recognise this version" (a request validation concern) — without forcing a global trade-off or per-endpoint stub repetition.

Happy to keep iterating on the API shape. Naming, default status code, controller-level inheritance behaviour, and AllowMultiple semantics are all open and the maintainer's call.

---

Reproducer

I put together a small standalone xUnit project that exercises the behaviours described above against Asp.Versioning.Mvc 10.0.0 on net10.0. Each test prints the observed status, content-type and body for the evidence trail. The zip is attached; dotnet test from the root runs it.

The suite covers: bare [MapToApiVersion] on a v2-only action under v1 → 400 + problem+json shape; default UnsupportedApiVersionStatusCode = 400; ?api-version= unknown → 400; [MapToApiVersion] filters before content-negotiation; [ApiExplorerSettings(IgnoreApi = true)] filters the v1 stub from the v1 OpenAPI document; the v1 stub action runs without needing a multi-MIME [Consumes] enumeration to dodge a 415.

[xavierjohn]

verify-asp-versioning-claims.zip

[xavierjohn]

Forward-compatibility: what happens when v3 ships?

One more angle worth surfacing — and it might be the strongest argument for the proposal.

Today

Take the BEFORE example and ship 2027-06-01. The controller becomes:

[ApiController]
[ApiVersion("2026-11-12")]
[ApiVersion("2026-12-01")]
[ApiVersion("2027-06-01")]   // newly added
[Route("api/[controller]")]
public sealed class OrdersController : ControllerBase
{
    // shared GETs — automatically participate in v3 ✓

    // v2-introduced, still alive in v3:
    [HttpPost("{id:int}/return"), MapToApiVersion("2026-12-01")]
    public Task<ActionResult<OrderResponse>> Return(...) { ... }
}

A v3 caller hitting POST /api/orders/42/return?api-version=2027-06-01 gets:

HTTP/1.1 400 Bad Request
{
  "type": "https://docs.api-versioning.org/problems#unsupported",
  "title": "Unsupported API version",
  "status": 400,
  "detail": "... does not support the API version '2027-06-01'.",
  "code": "UnsupportedApiVersion"
}

The same wall the v1 caller used to hit. [MapToApiVersion] is exact-match, so the action only matches v2. Every endpoint that was introduced in a prior version and is still alive in v3 has to be hand-edited:

[MapToApiVersion("2026-12-01", "2027-06-01")]   // every release, every still-alive action

Miss one, and v3 callers get 400 on a URL they could call yesterday under v2 — and the v3 OpenAPI document silently drops the endpoint. There's no compile-time signal; it's a search-and-revisit chore against a list the codebase doesn't maintain anywhere.

(Verified — added a v3 case to the reproducer, returns 400 as predicted. Test name Claim_08_NewVersionV3_existingMapToApiVersion_returns400.)

With [IntroducedInApiVersion]

[HttpPost("{id:int}/return")]
[IntroducedInApiVersion("2026-12-01")]
public Task<ActionResult<OrderResponse>> Return(...) { ... }

Adding [ApiVersion("2027-06-01")] to the controller is the only edit. The action's effective version set is recomputed as { v ∈ declared : v ≥ 2026-12-01 }, which now includes v3. No further changes; no codebase-wide sweep.

"But how does the framework know which versions come after 2026-12-01?"

It doesn't have to. The attribute is interpreted as a filter over the controller's declared version set, not a forward-looking declaration in absolute time:

controller declared versions = { 2026-11-12, 2026-12-01, 2027-06-01 }   // from [ApiVersion] attrs
[IntroducedInApiVersion("2026-12-01")] on action
  ⇒ effective set = { v in declared : v ≥ 2026-12-01 }
                  = { 2026-12-01, 2027-06-01 }

That's the same lookup the framework already does to decide a [MapToApiVersion("2026-12-01")] action is reachable under v2 — just ≥ instead of ==. No new "set of all known versions" needs to be tracked outside what the controller already declares. (Or, with VersionByNamespaceConvention / a versioning policy, whatever set the framework's ApiVersionModel already exposes for that controller.)

Implication for the proposal

This shifts the value framing slightly. The v1-stub argument is about saving 4–5 lines per v2-only endpoint at the moment of introduction. The v3 forward-compat argument is about avoiding a recurring per-release sweep for every endpoint that has ever been introduced in a prior version. The former is a one-time tax; the latter is a tax on every release going forward, paid by humans who have to remember it. The attribute removes both.

This also keeps [MapToApiVersion] as the right tool for the genuinely-version-pinned case (e.g., "this action is v2-only, removed in v3") — the two attributes have distinct, non-overlapping semantics.

[commonsensesoftware]

You have a misunderstanding of the RFC and meaning.

/api/orders/42 is the identifier of the resource. This exists for all possible versions. The API version is technically the representation. This would no different than if you asked for application/xml for a resource that can only be represented by application/json (406). [MapToApiVersion] is doing exactly what it is intended to do.

The choice to use 400 indicates the resource might exist, but you didn't ask for it correctly. In this scenario, that means at least /api/orders exists. If /api/orders or /api/orders/42 truly does not exist, then the client receives 404; regardless of API version. An API version is part of the resource nor does it identify it; it indicates how the resource is to be represented. The endpoint doesn't exist is an implementation detail. HTTP is the API.

API version ranges are intentionally unsupported out-of-the-box. There is no universal way to have the correct behavior because it is almost always application-specific. The necessary extension points exist for you to create them however.

API version interleaving is supported, but it should be used sparingly - if at all. It introduces a number of complexities as you have outlined.

[xavierjohn]

Thanks for taking the time to lay out the framing — that's a useful clarification of how the library views API version vs. resource identity, and I take the point about preferring sparingly-interleaved versions architecturally.

Given that, I'd like to take you up on the pointer to the extension surface. Could you point me at the right hook(s) for implementing this behaviour in user code? Specifically I'm looking for whichever extension point(s) let me:

1. Mark an action so that requests under earlier versions return 404 (or another configurable status) rather than the default 400 — without changing the global UnsupportedApiVersionStatusCode.
2. Have that same marking exclude the action from earlier versions' OpenAPI documents (i.e., participate in Asp.Versioning.Mvc.ApiExplorer's grouping).
3. Have it interpreted as "from this version onward against the controller's declared set" so a new [ApiVersion("…")] declaration on the controller automatically picks the action up.

I can see candidates in the public surface — IApiVersionConvention, IControllerConvention, IActionConvention, the various IApiVersionFilter / IApiVersionSelector types, and the ApiVersionModel plumbing — but I'd rather follow your guidance on the intended seam than pick the wrong one and end up fighting the framework. A one-line "start with X" would be enough; I'm happy to do the implementation work and write it up as a sample.

If there isn't a natural seam for (2) — the API Explorer / OpenAPI filtering — that's also useful information; I'd treat it as a separate gap to handle on our side.