'Fallback' versioning support

[xdeng-msft]

Hi, I am trying to implement 'Fallback' api version that would programmatically select the latest implemented API which <= the requested API version.

I have read through most of the related topics and I understand the main concern of 'API versions must be discrete' - we are using date-based versioning (group version) and we want each version to provide a complete set of all the available APIs; while those versions might differ in some of the APIs, most of the APIs would still be served by the existing endpoints and that is just an implementation details of the service. As we have tons of APIs, it's rather error-prone to require us to explicitly add the new version (e.t., using the IApiVersionProvider) into the existing endpoints.

I was reading the #762 and that basically aligns with what I was trying to do. However, with 'Asp.Versioning.Mvc.ApiExplorer' 8.1.0 and .net 8, that did not seem to work anymore. The request always seem to hit an UnsupportedApiVersionEndpoint even though the RequestedApiVersion has been overwritten to the fallback one very early in the request pipeline (e.g., before routing is done).

Am I missing something? Or I would need to add a customized ApiVersionMatcherPolicy? Any guidance would be greatly appreciated! Thanks!

[commonsensesoftware]

Fallback and backward compatible are fallacies and a bad idea. It's almost always ends badly for the client. I've just added additional feedback to discussion #971. The only provided method supported out-of-the-box is using the CurrentImplementationApiVersionSelector, which will select the current (e.g. highest) API version available; however, this logic is only ever evaluated if the client does not specify an API version. These capabilities were only ever intended as default options for previously unversioned clients.

Unless you completely own the server and client side, you cannot make any safe assumptions about a client behavior. Even additive changes can be breaking. Yes - a client should and probably is using a tolerant reader, but you can't guarantee that. If the client performs schema validation? I've seen it. This will break a client because you've altered the contract without telling them. This is the entire point of API Versioning to begin with.

It sounds like your issue and challenge is a lot less about managing versions and more about managing the server-side implementation. There are a lot of ways to manage that. First, you should have a well-defined versioning policy; for example, N-2 versions. That alone will cut down management to 3 versions and limit proliferation. If you're going to have pre-releases, you should have policies around those too, which might just be N or N-1.

There's no getting around IApiVersionProvider. That's the core abstraction and is the hook that provides the metadata for API Versioning to achieve most of it's value-add. You are in no way limited to attributes though. You can use conventions provided out-of-the-box or you can roll your own. The VersionByNamespaceConvention applies an API version to controllers based on their .NET namespace. You can use other approaches that might use information from configuration or a data store. Creating new API versions can be as simple as copy and replace into a new folder and removing an API version can be simple as deleting a folder. I don't recommend inheritance, but that's possible too. Proper factoring of the services and components behind the APIs should allow use across all of your API versions without giving the client a moving target.

[xdeng-msft]

Really appreciate the promote response, @commonsensesoftware ! My apologies for using the overloaded term 'fallback', I think that has caused a lot of confusions.

The apiversion in our case is essentially a group of a complete API set which contains several APIs like 'Get /foo' and 'Get /bar'. I am not trying to 'overwrite' the requested apiversion, but rather to tell the routing system that 'Get /foo?apiversion=2025-04-15' should be served by controller action GetFoo which is annotated with version 2025-01-01 as the contract did not change for the API, between those 2 versions. If we are ever going to make changes to the 'Get /foo' api, a new controller action would be added and annotated with a newer version (e.g., 2026-01-01).

The VersionByNamespaceConvention would still be too much of work to us as we have ~100 APIs from 30+ controllers, and we are supporting 10+ versions at the moment - needing to create a new namespace and copy & paste all the controllers is unfortunately highly risky, as again we need to make sure each version is a complete API set. Not to mention the added size of the binary & other performance impact.

I get that there is no getting around IApiVersionProvider, but I can't figure out a way to make aware of all the explicitly declared APIs and their corresponding versions. If I am not mistaken, the convention is operated at a per-controller basis, while for our case different versions of the same API (Get /foo) could be implemented in different controllers.

I feel like unless I have the IApiVersionDescriptionProvider / ApiVersionModel ready, I will have to do my own aggregation to know between version X and Y (in chronological order), what versions have not been explicitly annotated (implemented with a controller action) and then apply the convention to fill the gaps - that's why I was originally looking into middleware as that would reuse most components of the APIVersioning without touching too much of the internal abstraction. Should I be looking into the IApplicationModelProvider then, as that's the place we would have access to all the API controllers? Am I on my own to roll something out to collate API versions, based on the route?

I hope this makes sense. Thanks!

[commonsensesoftware]

This is good, I think. 😉 Let me try to play back what you want.

Your APIs have symmetrical versions from the client's perspective. If you are on 2025-01-01 all of the APIs exists. If you move to 2026-01-01, all of the versions should exist, even if no changes have been made. In other words, you want a 2025-01-01 API to automatically handle 2026-01-01 without having to touch anything. This is really all about server-side implementation and management. I get it. It makes sense; however, there are some nuances.

The most obvious problem is sunsetting an API. If an API is completely removed from 2026-01-01, how would you know or reason about not providing a mapping/route to it? When should API versions start filling in? You'd have to make an assumption that the lowest API version you can find for an API is the starting point for its existence/inclusion. Another issue is what the step should be? This is kind of where the API Explorer might be able to help. It only works under the assumption that it can report all possible API versions and they symmetrical across the board. That is effectively how API version-neutral APIs are reported to OpenAPI. The challenge to making that work is a 🐔 and 🥚 problem. You want to use the API Explorer to fill in the API version gaps, but you need the API versions to build the collated set of API versions gathered by the API Explorer.

This isn't impossible to do, but much of how it should work and behavior is specific to you. I thought about such a feature before, but it's hard to create a solution that works for everyone. You might find #458 useful. There are several issues regarding ranges and symmetrical versioning. I thought I had created a skeleton of a solution somewhere in the issues and/or StackOverflow (SO) that showed what it could look like, but I'm not finding it. You might have been luck spelunking.

Honestly, I would be cautious with implicitly deriving ranges and filling in gaps. It's convenient, but it's a lot harder to reason about. You'll want rigorous tests to make sure APIs start and end at the correct versions. The easiest, safest, and most understandable will be to start with something like using a range or even just multiple versions on controllers/endpoints. Depending your release cadence and versioning policy, that really shouldn't be that painful. That would, at least, get you on your way. After you have a working path, you can consider how to automate the process. Assuming you are using controllers, the way I think you might do that is via a custom IApplicationModelProvider. You would need to let the default API Versioning implementation run first. You don't have control over ordering, so you'd need to make sure yours is registered last or you decorate over the default implementation; there can be multiple providers. By the time your provider is run, you expect that all controllers and actions have been discovered and their API versions are collated. You would then need to collate all possible API versions, similar to what the API Explorer does. At this point, you should be able to enumerate back through all of the discovered ControllerModel instances and fill in the gaps from the collated set, starting at the lowest implemented API version and where the version is not implemented by another controller. This easily gets complex.

Consider:

// using VersionByNamespaceConvention
namespace Api
{
	namespace v2025_01_01.Controllers
	{
		[ApiController]
		[Route("[controller]")]
		public sealed class Demo1Controller: ControllerBase
		{
			[HttpGet]
			public IActionResult Get() => Ok();
		}
	}

	namespace v2026_01_01.Controllers
	{
		[ApiController]
		[Route("[controller]")]
		public sealed class Demo2Controller: ControllerBase
		{
			[HttpGet]
			public IActionResult Get() => Ok();
		}
	}

	namespace v2027_01_01.Controllers
	{
		[ApiController]
		[Route("[controller]")]
		public sealed class Demo1Controller: ControllerBase
		{
			[HttpGet]
			public IActionResult Get() => Ok();
		}

		[ApiController]
		[Route("[controller]")]
		public sealed class Demo2Controller: ControllerBase
		{
			[HttpGet]
			public IActionResult Get() => Ok();
		}
	}
}

v2025_01_01.Controllers.Demo1Controller is defined for 2025-01-01 and v2027_01_01.Controllers.Demo1Controller is defined for 2027-01-01, but there is a gap. The assumption is that v2025_01_01.Controllers.Demo1Controller should implicitly declare (and implement) 2026-01-01, but not 2027-01-01. This only works as long as there at least one API for 2026-01-01, which is defined by v2025_01_01.Controllers.Demo2Controller. This should all be possible, but there is a lot of collation and resolution required to figure it out. This still doesn't address where to clip versions at. For example, if v2026_01_01.Controllers.Demo2.Controller was sunset in 2027-01-01, how do you know? What information can you use to determine that? You would likely need something specific to your app, be it a custom attribute, configuration value, or just the internal details. Only you know which version to stop on for an API in your application.

You can get a sense of how to implement IApplicationModelProvider by looking at:

https://github.com/dotnet/aspnet-api-versioning/blob/main/src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/ApiVersioningApplicationModelProvider.cs

Hopefully, I've understood things correctly and this gets you on your way.

[xdeng-msft]

Thanks @commonsensesoftware ! Your understanding of the problem was spot on!

I did look into the #458 but later realized that, whenever a new version is introduced, one would need to go into the previous endpoints (that would have a new implementation), to declare a upper bound so the old endpoint would not be mapped to a new version implicitly - it's not that the process is painful, it's just that a manual process like this can go wrong easily.

I did think about the version removal and as you pointed out, this could be handled with some custom attribute to stop implicitly filling in the gaps.

I managed to write something quickly as a POC:

public sealed class SymmetricalApiVersionProvider : IApplicationModelProvider
{
    private readonly IApiControllerFilter controllerFilter;
    private readonly IOptions<MvcApiVersioningOptions> options;

    public SymmetricalApiVersionProvider(
        IApiControllerFilter controllerFilter,
        IOptions<MvcApiVersioningOptions> options)
    {
        this.controllerFilter = controllerFilter;
        this.options = options;
    }

    public int Order => -1; // Run before API Versioning

    public void OnProvidersExecuted(ApplicationModelProviderContext context) { }

    public void OnProvidersExecuting(ApplicationModelProviderContext context)
    {
        // Filter relevant controllers
        var controllers = controllerFilter.Apply(context.Result.Controllers);

        // Group actions and their versions by route template
        var groupedActions = controllers
            .SelectMany(controller => controller.Actions.SelectMany(action => GetActionRoutes(controller, action)))
            .GroupBy(route => route.Template);

        // Process each group to identify and fill version gaps
        foreach (var group in groupedActions)
        {
            var actionsAndVersions = group.Select(route => (route.Action, route.Versions)).ToList();
            var allImplementedVersions = actionsAndVersions
                .SelectMany(av => av.Versions)
                .ToList();

            // Find and fill gaps for stable versions
            FillVersionGaps(Version.StableVersions, allImplementedVersions, actionsAndVersions, null);

            // Find and fill gaps for preview versions
            FillVersionGaps(Version.PreviewVersions, allImplementedVersions, actionsAndVersions, Status.Preview);
        }
    }

    private IEnumerable<(string Template, ActionModel Action, List<ApiVersion> Versions)> GetActionRoutes(ControllerModel controller, ActionModel action)
    {
        var versions = action.Attributes
            .OfType<IApiVersionProvider>()
            .SelectMany(provider => provider.Versions)
            .ToList();

        foreach (var controllerSelector in controller.Selectors)
        {
            foreach (var actionSelector in action.Selectors)
            {
                var route = AttributeRouteModel.CombineAttributeRouteModel(
                    controllerSelector.AttributeRouteModel,
                    actionSelector.AttributeRouteModel
                );

                if (route?.Template != null)
                {
                    yield return (route.Template, action, versions);
                }
            }
        }
    }

    private void FillVersionGaps(
        IEnumerable<ApiVersion> targetVersions,
        List<ApiVersion> allImplementedVersions,
        List<(ActionModel Action, List<ApiVersion> Versions)> actionsAndVersions,
        string? status)
    {
        var versionGaps = targetVersions.Except(allImplementedVersions);

        foreach (var gap in versionGaps)
        {
            // Find the closest action model supporting the largest version < the gap
            var closestAction = actionsAndVersions
                .Where(av => av.Versions.Any(v => v < gap && v.Status == status))
                .OrderByDescending(av => av.Versions
                    .Where(v => v < gap && v.Status == status)
                    .Max())
                .FirstOrDefault();

            if (closestAction.Action != null)
            {
                // Apply the convention to the action
                var conventionBuilder = options.Value.Conventions
                    .Controller(closestAction.Action.Controller.ControllerType)
                    .Action(closestAction.Action.ActionMethod);
                conventionBuilder.HasApiVersion(gap);
            }
        }
    }
}

This feels sketchy to me as I had to basically collate on the route template - do you see any better way to do it? Also I had the provider run before the API versioning one as I was basically doing my own version discovery (by attribute) and I need the API versioning one to apply the convention for me. Do these make sense? Would love to see if I am heading on the right direction before doing any optimization & edge case handling to the code.

And lastly, assuming we are ok with that the routing system not aware of the gap version(s), is there really no way to just 'overwrite' (sry for using the term again) the selected API version and have the request routed to the endpoint that supports the overwritten version, so that the service would more or less behave in the way we want? I still feel like that would be the cleanest solution given our requirements.

[commonsensesoftware]

A couple of things. First, I guess I forgot that IApplicationModelProvider does have an order - yay. Better still, I apparently did have the foresight to think that someone might want to extend ApiVersioningApplicationModelProvider at some point. You can simply create a new provider and override OnProviderExecuted to do some post-processing (e.g. fill in the gaps). You would then remove ApiVersioningApplicationModelProvider from DI and register your own type (remember that there can be many providers).

Regardless of method you choose, you don't need to do all of the aggregation - again. To understand the process you can follow:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/Conventions/ControllerApiVersionConventionBuilderBase.cs

Line 50 in 39cfc87

private void ApplyActionConventions( ControllerModel controller )

which will call through to:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/Conventions/ActionApiVersionConventionBuilderBase.cs

Line 17 in 39cfc87

public virtual void ApplyTo( ActionModel item )

this will add ApiVersionMetadata as endpoint metadata:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/ApplicationModels/ModelExtensions.cs

Line 35 in 39cfc87

internal static void AddEndpointMetadata( this ActionModel action, object metadata )

There isn't an API to get it out because you add them one at a time, but there can be many. For vanilla ASP.NET Core, there should only be one. When working with OData, there are many. Just something to be aware of. All of the types and APIs are public so you can get to them.

You can then you use the ApiVersionMetadata to collate all API versions as well as by specific API. Collation is done by API name, not by route template. This is because semantically equivalent templates differ. Consider value/{id}?api-version=1.0 and value/{id:int}?api-version=2.0. These are equivalent, but different. Template variation can be wildly more complex. The logical API name is really the only thing to key off of. This is how the API Explorer does it's work. You can test if a particular API version is declared by an endpoint using:

aspnet-api-versioning/src/Abstractions/src/Asp.Versioning.Abstractions/ApiVersionMetadata.cs

Line 121 in 39cfc87

public ApiVersionMapping MappingTo( ApiVersion? apiVersion )

An Explicit mapping means the action itself declares the API version. This is supported and allowed, but you would typically want to get it from the controller. That will be mapped as Implicit. None means it's not mapped at all.

Once you've figured out where you need to fill in gaps, you can then deconstruct the metadata into constituent parts:

aspnet-api-versioning/src/Abstractions/src/Asp.Versioning.Abstractions/ApiVersionMetadata.cs

Line 176 in 39cfc87

public void Deconstruct( out ApiVersionModel apiModel, out ApiVersionModel endpointModel, out string name )

and then reassemble each ApiVersionModel

aspnet-api-versioning/src/Abstractions/src/Asp.Versioning.Abstractions/ApiVersionModel.cs

Line 117 in 39cfc87

public ApiVersionModel(

Declared API versions are the most important. That is the list considered for routing. The others are just collated metadata for reporting API versions in responses and OpenAPI. You likely only need to update the API Model, which is the model for the whole API presented by the endpoint (e.g. the controller). The Endpoint Model is the model for the action itself. This is how things are tracked internally to distinguish between what is explicitly declared on an action (the highest precedence) and what is inherited from the controller implicitly.

At this point, you shouldn't have to do anything else. The rest of the magic takes over. All of that information is used to build the route tables, which you can peek at here:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Http/Routing/ApiVersionMatcherPolicy.cs

Line 170 in 39cfc87

public IReadOnlyList<PolicyNodeEdge> GetEdges( IReadOnlyList<Endpoint> endpoints )

I would avoid diving that far down and mucking with it. It should be a lot easier to do and reasonable about just filling in gaps in the metadata.

Finally, with respect to explicitly setting the API version in the request pipeline, that is certainly possible. I don't see how that will help you though. This achieved through: HttpContext.ApiVersioningFeature().RequestedApiVersion = new(1.0); This is exactly what AssumeDefaultVersionWhenUnspecified does.

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Http/Routing/ApiVersionMatcherPolicy.cs

Line 89 in 39cfc87

if ( apiVersion == null && Options.AssumeDefaultVersionWhenUnspecified )

The problem will be how do you know you should do that? No endpoint has been selected. Again, this is a 🐔 and 🥚 problem. How can you know which API version to advance or set to if you don't even know which endpoint is the target - yet? To the best of my knowledge, there is not a way to reach a destination endpoint in the routing system, only to opt to re-enter the process and select a different endpoint. The API version itself is part of the route selection process. If you're that curious, you can generate a DAG by running the acceptance tests and open the link from one of them in a browser to see how things are mapped visually.

Attempting to match it yourself will be difficult or impossible. Consider you only have endpoints with a template such as value/{id}. You have to somehow match that against http://my.api.com/value/42?api-version=1.0. It's not easy and you're arguably doing what the routing system is already doing. I already had to do something like this for URL segment versioning (the only not RESTful method 😞). I can only get the value from the URL, but how? The routing system will bucketize the tree. Once I get down to a jump table of candidates, I can use any of the endpoints to extract the version for the URL. This is possible because it's behind a route constraint that must have a well-known, configured name. This is one of the uses of ApiVersioningOptions.RouteConstraintName, which might otherwise seem not very useful. This type of approach is not for the faint of heart and it's pretty slow:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Http/Http/HttpRequestExtensions.cs

Line 27 in 39cfc87

public static bool TryGetApiVersionFromPath<TList>(

Honestly, I realize that it might seem simpler; especially since you probably understand middleware very well. In this case, it's a lot more complex that just dropping in some middleware and tweaking some things in the request. I've given you some pointers where to look and warned you about the dragons. If you really want to go on an adventure, that's the way. I think you'll have faster and easier success just dealing with the metadata.

[xdeng-msft]

@commonsensesoftware Sir this is amazing!

this is a 🐔 and 🥚 problem. How can you know which API version to advance or set to if you don't even know which endpoint is the target

I think I get it now - before the routing is done, the endpoint candidate(s) is undetermined and hence there is no way to know the implemented versions for the particular API; after routing is done it's already too late as the ApiVersionPolicyJumpTable already set the endpoint to 400.

I indeed was looking into the MatcherPolicy and tried messing around with the PolicyJumpTable, which indeed turned out to be more complicated.

You can then you use the ApiVersionMetadata to collate all API versions as well as by specific API. Collation is done by API name, not by route template.

This is the final piece that's missing:

aspnet-api-versioning/src/AspNetCore/WebApi/src/Asp.Versioning.Mvc/Conventions/ActionApiVersionConventionBuilderBase.cs

Line 24 in 39cfc87

var name = NamingConvention.GroupName( controller.ControllerName );

It seems like the name is always set to the controller's name. Am I missing something here?

[commonsensesoftware]

That's correct, but IControllerNameConvention controls exactly how it gets generated. The default will be ExampleController, Example1Controller, and Example2Controller will all have the group name of Example. This is how all API versions are collated for routing and the API Explorer. 😁

[xdeng-msft]

@commonsensesoftware I am confused now.

Consider:

namespace Api
{
	[ApiController]
	public sealed class DemoController: ControllerBase
	{
                [ApiVersion("2025-01-01")]
		[HttpGet("foo")]
		public IActionResult GetFoo() => Ok();
	}

        [ApiController]
	public sealed class AnotherDemoController: ControllerBase
	{
                [ApiVersion("2027-01-01")]
		[HttpGet("foo")]
		public IActionResult GetFoo() => Ok();

                [ApiVersion("2026-01-01")]
		[HttpGet("bar")]
		public IActionResult GetBar() => Ok();
	}
}

How do I collate the implemented versions for API 'Get foo' then? The ApiVersionMetadata on the DemoController#GetFoo & AnotherDemoController#GetFoo would now give me different names, while logically they should be the same API and only differ in apiversions.

[commonsensesoftware]

While in the strictest since a single action can be considered an API, that is almost never the case. Any method on class Demo is an API, but you likely wouldn't discuss it like that. You would call it the foo method on Demo API. Web APIs are typically discussed and organized the same way. Given the Uniform Interface constraint, you should thing of a HTTP API as response http.get(request). The HTTP method is the API method.

OpenAPI and the SwaggerUI also organize things this way. You don't navigate individual endpoints. It instead looks like:

• 2025-01-01
  • Demo
    • GET /foo
• 2027-01-01
  • Demo
    • GET /foo
    • GET /bar

Exactly how you name and group is up to you, but it's generally by controller name because the controller represents the logical API name - e.g. the Demo API. This also is the most natural to what people are used to before versioning and typically doesn't require any additional configuration or code.

The default convention will drop off the Controller suffix, but API versioning adds the addition convention to trim off the trailing numbers. This is to accommodate limitations in the underlying language - namely C#. You can't have more than one type with the same name in a namespace. Let's say you wanted to organize things as:

• Api
  • Demo
    • DemoController
    • Demo2Controller
    • Demo3Controller

Trimming off Controller would leave Demo, Demo2, and Demo3, but they are all the Demo API. This is lame if you have to configure all of that. The default convention trims that off so that they are all Demo and collated together.

There are edge cases where you don't want this. Let's say your controller was named S3Controller (in relation to AWS S3) or something like Catch22Controller. You would not want the numbers trimmed off in these cases. The convention can be change so that won't happen.

Regardless of the default convention, it is also possible to set [ControllerName("Demo")] to explicitly set what the name should be. If you organize by namespace, then it's irrelevant.

• Api
  • v2025_01_01
    • DemoController
  • v2027_01_01
    • DemoController

Now they are all plainly Demo. This eventually lends to "If controllers are organized by namespace and that namespace is a 'version', why I can't that automatically be applied to the controller/API". That's exactly what the VersionByNamespaceConvention does. 😁

This would produce the original layout listed above.

I would advise against versioning at the specific endpoint/action level. It might seem logical, but it'll likely give you grief elsewhere, such as OpenAPI. It will also result in a lot more configuration. I'm actually trying to remember how that groups in OpenAPI 🤔 . IIRC it looks quite strange. The main reason I ever even enabled that scenario is the edge case for something like:

[ApiController]
[Route("[controller]")]
public sealed class Demo1Controller: ControllerBase
{
	[HttpGet]
	public IActionResult Get() => Ok();

	[ApiVersionNeutral]
	[HttpDelete("{id}")]
	public IActionResult Delete(string id) => NoContent();
}

DELETE APIs tend to be version-neutral, but you don't want the entire API like that, just one specific endpoint.

The same behavior exists for Minimal APIs too. A group of APIs has a logical name that constitutes the overall API.

I hope that helps clarify things.

[xdeng-msft]

@commonsensesoftware thanks for clarifying.

It sounds like the fundamental assumption is that, if one of the endpoints / actions for an API (resource) has a new version, then the rest of the endpoints / actions would also have a new version. This might not always be true and is especially important for 'Symmetrical API versioning' - chances are that only the write endpoints (Create and update) needs a new implementation to accommodate a new feature, but the read & write do not (this might sound weird but let's assume it's the case per our implementation details). I will need a way to reliably collate the 'declared versions' for read & delete (across all the 'demo' controllers) and attach the metadata to fill the 'gaps'.

After thinking more about the value/{id}?api-version=1.0 and value/{id:int}?api-version=2.0 case, I am now actually leaning more towards the IEndpointSelectorPolicy approach and I now have something like this:

public sealed class SymmetricalApiVersionMatcherPolicy : MatcherPolicy, IEndpointSelectorPolicy
{
    public SymmetricalApiVersionMatcherPolicy(
        IApiVersionParser apiVersionParser,
        IEnumerable<IApiVersionMetadataCollationProvider> providers,
        IOptions<ApiVersioningOptions> options,
        ILoggerFactory loggerFactory)
    {
        DefaultMatcherPolicy = new ApiVersionMatcherPolicy(apiVersionParser, providers, options, loggerFactory.CreateLogger<ApiVersionMatcherPolicy>());
    }

    private ApiVersionMatcherPolicy DefaultMatcherPolicy { get; }

    public override int Order => DefaultMatcherPolicy.Order;

    public bool AppliesToEndpoints(IReadOnlyList<Endpoint> endpoints) => DefaultMatcherPolicy.AppliesToEndpoints(endpoints);

    public async Task ApplyAsync(HttpContext httpContext, CandidateSet candidates )
    {
        var highestMatchingVersion = ApiVersion.Neutral;
        var targetIndex = -1;

        for (var i = 0; i < candidates.Count; i++)
        {
            // Note: Don't skip invalid candidate for now as that seems to be safer.
            // Consider routes like /hostpools/{id} and /hostpools/{id:int} are semantically equivalent, but different
            // templates - a request like /hostpools/abc?api-version-2025-04-18 will match both candidates in the DFA graph
            // while only the first one is valid. If all of them are eligible for fallback (e.g., first one is versioned
            // as 2025-01-01 and second one is versioned as 2025-02-01), then skipping invalid candidates will end up with
            // 'dynamic' fallback versions, depending on whether the id in the request is an integer or not.

            // if (!candidates.IsValidCandidate(i))
            // {
            //     continue;
            // }

            // make all candidates invalid by default
            candidates.SetValidity(i, false);

            var candidate = candidates[i];
            var apiVersion = candidate.Endpoint.Metadata.GetMetadata<ApiVersionMetadata>();

            if (apiVersion == null)
            {
                continue;
            }

            ApiVersionModel model = apiVersion.Map(ApiVersionMapping.Explicit);
            ApiVersion currentBestMatch = SelectVersion(httpContext.Request, model);

            if (highestMatchingVersion == ApiVersion.Neutral || currentBestMatch >= highestMatchingVersion)
            {
                highestMatchingVersion = currentBestMatch;

                targetIndex = i;
            }
        }

        if (targetIndex < 0)
        {
            await DefaultMatcherPolicy.ApplyAsync( httpContext, candidates );
            return;
        }

        // we only set the candidate with the latest version < requested version as valid - Note: it might still be an
        // 'invalid' candidate (e.g., constraint violation?). In that case we want 400 to be returned by, e.g., model binding
        candidates.SetValidity(targetIndex, true);
        var feature = httpContext.ApiVersioningFeature();
        feature.RequestedApiVersion = highestMatchingVersion;
    }

    private static ApiVersion SelectVersion(HttpRequest request, ApiVersionModel model)
    {
        ApiVersion? requestedVersion = request.HttpContext.GetRequestedApiVersion();

        if (requestedVersion is null)
        {
            // TODO: chose an alternate fallback
            return ApiVersion.Neutral;
        }
        
        return model.DeclaredApiVersions.LastOrDefault(version => version <= requestedVersion) ?? ApiVersion.Neutral;
    }

This seems to work per my basic testing.

I do have a few things would love to confirm with you:

1. What does the ApiVersionPolicyJumpTable really do? Looks like without it I am still getting a pretty clear CandidateSet to work with.
2. I noticed that the ApiVersionMetadata on all the candidates would contain versions declared by endpoints with the same route - it looks like some collation by route is still happening before the ApiVersionMetadata is applied to the endpoint. Can you point me to where it's done?
3. I am still a bit confused on the apiModel & endpointModel (in the context of the ApiVersionMetadata) - is the apiModel an aggregated model across all endpoints for the same resource (e.g., aggregated by controller), or it's only the aggregation of endpoints with the same route?

Thanks again!

[commonsensesoftware]

1. The ApiVersionPolicyJumpTable is what builds the edges and is ultimately how the route tree is built
2. For MVC Core and controllers, all collation is done via the IApplicationModelProvider
   a. It is done exactly once at startup time and is immutable after that
3. The apiModel is the model defined by the API, which in your case is the controller
   a. The API is derived from a group for Minimal APIs, but it's otherwise equivalent to a controller
   i. You also notice that a name is not required, but that's because you explicitly create a group and all endpoints in the group are part of the API; regardless of name. If you specify a name, however, that's the logical API name.
   b. The endpointModel is the model defined for a specific endpoint
   i. You can mix and match implicit models from the deriving client and explicit models on an endpoint.
   ii. This keeps them separated in a clear way
   iii. Explicit endpoint configuration always trumps implicit API configuration

Using the IEndpointSelectorPolicy like that probably will not work the way you think. IIRC, the routing system is not guaranteed to ApplyAsync and it may call through multiple times. IMHO, you'll have more success with just mucking around with the metadata and collation.

[xdeng-msft]

@commonsensesoftware I feel like there are still some misunderstandings.

you'll have more success with just mucking around with the metadata and collation.

I assume for metadata you meant using a custom ApiVersioningApplicationModelProvider to apply the ApiVersionMetadata to the endpoint (to fill the gaps).

As discussed earlier, I don't see how I would be able to collate the versions without parsing the routing template. Imagining the service needs to support 3 versions '2025-01-01', '2026-01-01' and '2027-01-01', and the Demo API is implemented as:

[ApiController]
[Route("[controller]")]
[ApiVersion("2025-01-01")]
[ApiVersion("2026-01-01")]
public class DemoController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("2025-01-01")]
    public IActionResult GetV1()
    {
        return Ok();
    }

    [HttpGet]
    [MapToApiVersion("2026-01-01")]
    public IActionResult GetV2()
    {
        return Ok();
    }

    [HttpPut]
    [MapToApiVersion("2025-01-01")]
    public IActionResult PutV1()
    {
        return Ok();
    }
}

To make this API supports all 3 versions, I will need to

1. collate all declared versions for Get /Demo and Put /Demo (not by controller)
2. find out the gaps for the API (which is 2027-01-01 for Get /Demo and 2026-01-01 & 2027-01-01 for Put /Demo)
3. find out the highest declared version <= 2027-01-01 for Get /Demo (that would be 2026-01-01).
4. annotate the GetV2 endpoint (as it has a declared version of 2026-01-01) with a new endpointModel that supports both 2026-01-01 and 2027-01-01
5. find out the highest declared version <= 2027-01-01 for Put /Demo (that would be 2025-01-01).
6. annotate the PutV1 endpoint (as it has a declared version of 2025-01-01) with a new endpointModel that supports all 3 versions.

Noted that it's important that I won't do anything to the GetV1 endpoint as it should still serve and only serve the Get /Demo?api-version=2025-01-01 request.

Without parsing the route templates, how do I know that Get /Demo 'supports' '2025-01-01' and '2026-01-01' already and I should make GetV2 (but not the GetV1) to also support '2027-01-01'? How do I know that Put /Demo only supports '2025-01-1' and I should make PutV1 to also support '2026-01-01' and '2027-01-01'?

With the IEndpointSelectorPolicy, my mentality would become pretty simple - to disambiguate the ambiguous endpoints, using the ApiVersionMetadata (e.g., always pick the endpoint with the highest version <= requested version); and override the RequestedApiVersion so it can be used by other api versioning components later in the request pipeline.

the routing system is not guaranteed to ApplyAsync and it may call through multiple times

Not sure I am getting it... My AppliesToEndpoints calls back to the ApiVersionMatcherPolicy#AppliesToEndpoints, so I assume my ApplyAsync would get called whenever the ApiVersionMatcherPolicy#ApplyAsync would get called. Or you were simply pointing out that fact that since I am not using the ApiVersionPolicyJumpTable (and not having the extra edges), my AppliesToEndpoints will get called with a different CandidateSet?

I don't really need API versioning to deny the request if the version is not supported or a version hasn't been specified - we have a gateway in front of our service, and it would only forward the request if the client has specified a supported API version. I also don't really need other fancy functionalities like 'making API explorer aware of all the symmetrical version endpoints'; 'OpenApi' nor 'ReportApiVersions' etc.

To its core, I am really only taking a dependency on the fact that API versioning components (mostly just the ApiVersioningApplicationModelProvider) would annotate the endpoints with their 'declared' version(s) (with the ApiVersionMetadata) and rely on the asp.net core in-built routing system to correctly send me the matching endpoints for me to 'disambiguate', based on the metadata on the endpoints. Unless asp.net core in-built routing system would sometimes send me a CandidateSet that doesn't contain, one or some of the endpoints for Get /Demo?

I know I have already asked too much, but I have huge respect to your contribution to the asp.net community and your opinion means a lot to me. I would really appreciate your final thought on this.

[xdeng-msft]

I happened to come across the dotnet/aspnetcore#33865 - that answered my original question on what the ApiVersionPolicyJumpTable is for and might as well explains why you mentioned 'the routing system is not guaranteed to ApplyAsync and it may call through multiple times'.

I think the behavior of vanilla asp.net, that it would eliminate certain endpoints when certain INodeBuilderPolicy is applied, is something I can work with for my very specific scenario.

Also as a FYI, I think the ConsumesMatcherPolicy doesn't exist anymore.

[commonsensesoftware]

Funny enough... that's my post. I thought I found a bug in the routing system, but it turns out that it was an edge case I can completely missed. That ultimately led me to a the path to completely overhaul routing in 6.0+. It's a lot more complicated and it was pretty tricky to retain as much old behavior as possible. I know just how deep the hole goes, which is why I don't recommend it.

[commonsensesoftware]

Apologies for not looking at your proposed implementation more closely. I thought I had pointed you in the right direction, but I see now that you were trying to redo all of the collation yourself. You do not need to that. You only need to take what's already been collated, figure out the gaps, and update the metadata with what you find. Routing will take over after that. It's going to be more involved for a complete solution, but it would likely look something like this:

public sealed class SymmetricalApplicationModelProvider : ApiVersioningApplicationModelProvider
{
    public SymmetricalApplicationModelProvider(
        IApiControllerFilter controllerFilter,
        IControllerNameConvention namingConvention,
        IOptions<ApiVersioningOptions> options,
        IOptions<MvcApiVersioningOptions> mvcOptions )
        : base( controllerFilter, namingConvention, options, mvcOptions ) { }

    public override void OnProvidersExecuted( ApplicationModelProviderContext context )
    {
        var (versions, buckets) = Bucketize( context.Result.Controllers );
        var controllers = context.Result.Controllers;

        for ( var i = 0; i < controllers.Count; i++ )
        {
            var actions = controllers[i].Actions;

            for ( var j = 0; j < actions.Count; j++ )
            {
                var metadata = actions[i].Selectors[0].EndpointMetadata.OfType<ApiVersionMetadata>().First();

                for ( var k = 0; k < versions.Length; k++ )
                {
                    var version = versions[k];

                    /* TODO: given the current API version and action/endpoint:
                     *
                     * 1. Find the next endpoint
                     * 2. Are there gaps between this endpoint and that endpoint's version
                     * 3. If no, move on
                     * 4. If yes:
                     *    a. Find the deltas in 'versions' between this endpoint and the next
                     *    b. Rebuild the ApiVersionModel for the 'API' associated with the endpoint
                     *    c. Rebuild the ApiVersionMetadata with the existing name, endpoint model, and new api model
                     *    d. Replace the SelectorModel metadata with the new ApiVersionMetadata
                     *    
                     * NOTE: you only know to stop when there are no candidates higher than the current version(s). you'll
                     * need something else to signal where to stop if you ever sunset an api version or have intended gaps.
                     */
                }
            }
        }
    }

    private static (ApiVersion[] Versions, Dictionary<string, ApiVersion[]> Buckets) Bucketize( IList<ControllerModel> controllers )
    {
        var versions = new SortedSet<ApiVersion>();
        var buckets = new Dictionary<string, SortedSet<ApiVersion>>( controllers.Count );

        foreach ( var metadata in EnumerateMetadata( controllers ) )
        {
            var model = metadata.Map( ApiVersionMapping.Explicit | ApiVersionMapping.Implicit );

            foreach ( var version in model.ImplementedApiVersions )
            {
                versions.Add( version );
            }

            if ( !buckets.TryGetValue( metadata.Name, out var bucket ) )
            {
                buckets[metadata.Name] = bucket = new();
            }

            foreach ( var version in model.DeclaredApiVersions )
            {
                bucket.Add( version );
            }
        }

        return (
            versions.ToArray(),
            buckets.ToDictionary( kvp => kvp.Key, kvp => kvp.Value.ToArray() ));
    }

    private static IEnumerable<ApiVersionMetadata> EnumerateMetadata( IList<ControllerModel> controllers )
    {
        for ( var i = 0; i < controllers.Count; i++ )
        {
            var actions = controllers[i].Actions;

            for ( var j = 0; j < actions.Count; j++ )
            {
                // this is an assumption that each action holds a single selector with api versioning metadata.
                // this holds true for most cases. odata is the only scenario I'm aware of that isn't
                yield return actions[i].Selectors[0].EndpointMetadata.OfType<ApiVersionMetadata>().First();
            }
        }
    }
}

I would avoid using version interpolation if you're going to fill in the gaps. It will must make it harder to reason about. Remember that mapping an API version does not declare it. It only marks which action/endpoint should be dispatched to for a given version of the API. It's not very intuitive., but declared versions on an action/endpoint specifically are mapped API versions unless there are no declared API versions (from the controller), which means the endpoint itself has a version. I'll try not to explain all the variations because it will probably confuse you. Choose a particular path and style, then stick with it. I recommend only versioning at the controller level with no interleaving. In fact, if you use the VersionByNamespace convention, you don't need any API versioning metadata expressed at all in the controllers. Everything will be by convention.

I hope that helps provide more clarity and give you some direction to move forward with.