Decouple the MatcherPolicy from MVC and make it solely based on routing.

[davidfowl]

The implementation could be made more generic by using endpoint metadata directly instead of the ActionDescriptor to stash the API information. Instead of doing SetProperty the data could be stored here.

I haven't looked deeply to see what other tentacles reach into MVC.

[commonsensesoftware]

Interesting that you mention that. A few people have asked how that might be achieved.

Switching from storing things in an ActionDescriptor to EndpointMetadata, or more specifically Endpoint.Metadata, is feasible - with the right amount of refactoring. API Versioning was around before Endpoint Routing (and helped flush out some of the design with Ryan and James). The two main reasons the information is still in a property are:

1. Historical
2. Continues to work for those still using legacy routing (they're still out there)

#2 can be addressed by the fact that you can't use both routing systems simultaneously. A strategy can be used to control where the information is accessed to avoid a bunch of branching conditions. Today, this would normally be detected through MvcOptions.EnableEndpointRouting. If MVC were removed, then it would probably be assumed true and only possibly switch when integrated with MVC.

I've also be considering breaking things further apart; something like Abstractions. This work and feature would likely align to those changes. Any thoughts or suggestions are most certainly welcome.

TL;DR

The fundamental challenge to removing MVC completely is how the metamodel is currently discovered. Version discovery and collation are largely done through the ApplicationModels namespace. In the strictest sense, API Versioning doesn't really care about that and isn't bound to it. A fairly early design point was API version information is purely metadata. It is provided by way of IApiVersionProvider. This is most commonly achieved by way of attributes, but there is a conventions fluent API as well. The Application Model afforded by MVC provides a nice way to inspect and apply API version metadata by interrogating the developer's code.

API version collation is one of the more difficult challenges. Despite what some people may think, it's achieved using the controller's name. Again - it's doesn't have to, but it was a natural choice. It might seem more logical to group by route template, but this can go sideways pretty quickly. For example, api/v{ver:apiVersion}/{id} and api/v{version:apiVersion}/{id:int} are semantically equivalent (and obvious to developers reading it), but is quite difficult - as well as likely slow - to match up. There are other scenarios where the route template just doesn't give you enough information. For example, what if value/{id} and value/{id}/subvalue/list should, or shouldn't, be grouped together? It's a bit more nuanced than that, but hopefully that paints a picture.

Armed with that information, what I conceptually think could work if those other issues are addressed would be something like:

app.UseEndpoints(endpoints =>
{
	// version-neutral api
	endpoints.MapGet("/ping", c => Task.CompletedTask)
	         .IsApiVersionNeutral();

	// 1.0 endpoint
	endpoints.MapGet("/hello", c => c.Response.WriteAsync("Hello world v1!"))
	         .HasApiVersion(1, 0);

	// 2.0 endpoints (grouped for convience)
	endpoints.WithApiVersion(2, 0, api =>
	{
	      api.MapGet("/hello", c => c.Response.WriteAsync("Hello world v2!"));
	});
});

I suspect this approach breaks or inhibits API Explorer features for those that care about it - usually for OpenAPI documents. I believe that's already an issue and an understood decision point for choosing this type of setup.

[davidfowl]

We're interested in this so we'll investigate what it would take to make it work in the .NET 7 timeframe.

[commonsensesoftware]

@davidfowl,

I just wanted to let you know that this work has been completed (but I'm not closing the issue just yet). Due to changes in the project that have just been announced, we're still a little bit out from publishing the corresponding packages. If you're interested in taking a peek, you can see the implementation here. Things are now split apart from core HTTP and MVC Core, where API Versioning is possible without any part or direct references to the MVC Core assembly. This also sets up the foundation for Minimal API support.

[commonsensesoftware]

As it relates to Minimal API, everything will tie together like this:

builder.Services.AddApiVersioning();

var app = builder.Build();

app.DefineApi()
   .HasApiVersion( 1.0 )
   .HasApiVersion( 2.0 )
   .ReportApiVersions()
   .HasMapping( api =>
    {
        // GET /weatherforecast?api-version=1.0
        api.MapGet( "/weatherforecast", () =>
            {
                return Enumerable.Range( 1, 5 ).Select( index =>
                    new WeatherForecast
                    (
                        DateTime.Now.AddDays( index ),
                        Random.Shared.Next( -20, 55 ),
                        summaries[Random.Shared.Next( summaries.Length )]
                    ) );
            } )
           .MapToApiVersion( 1.0 );

        // GET /weatherforecast?api-version=2.0
        api.MapGet( "/weatherforecast", () =>
            {
                return Enumerable.Range( 0, summaries.Length ).Select( index =>
                    new WeatherForecast
                    (
                        DateTime.Now.AddDays( index ),
                        Random.Shared.Next( -20, 55 ),
                        summaries[Random.Shared.Next( summaries.Length )]
                    ) );
            } )
           .MapToApiVersion( 2.0 );

        // POST /weatherforecast?api-version=2.0
        api.MapPost( "/weatherforecast", ( WeatherForecast forecast ) => { } )
           .MapToApiVersion( 2.0 );

        // DELETE /weatherforecast
        api.MapDelete( "/weatherforecast", () => { } )
           .IsApiVersionNeutral();
    } );

[davidfowl]

@commonsensesoftware We're also doing route grouping in .NET 7 dotnet/aspnetcore#36007 so we should make sure this gels with that. I'm curious to play with this though!

cc @halter73 @captainsafia

[commonsensesoftware]

@davidfowl,

Preview 2 is now available. The 🐀 🧶 has been eliminated. To the greatest extent possible, everything now only considers endpoints and their metadata.

New Packages:

• Asp.Versioning.Http - Minimal APIs
• Asp.Versioning.Mvc - MVC Core
• Asp.Versioning.Mvc.ApiExplorer - API Explorer extensions

Examples:

• Minimal API
• Minimal OpenAPI

The discussion on route grouping is progressing well, but some help may be needed in dotnet/aspnetcore#39604. Customers don't want to wait until .NET 7 for me to release an iteration. Ideally, I'd like to release within the next month. Since things are in preview now with a lot of breaking changes from previous versions, I'm ok with a few more. I don't want to repeat that in the .NET 7 release. Anything that we can to align direction (e.g. design + signatures) should be good for all. As can be seen here, I've had to resort to some pretty 🤮 hackery to retain parity with the out-of-the-box Minimal API support for the API Explorer.

@halter73 and I have had some discussion, but nothing is settled - yet.