commonsensesoftware
commented
3 years ago 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:
- Historical
- 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
captainsafia
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.