Is it possible to version by action/endpoint instead of controller?

[npbenjohnson]

I have 2 controllers with different versions (1.0, 2.0), and the same name, in different namespaces. I'm using the CurrentImplementationApiVersionSelector because versioning is being tacked on to a legacy project moving forward. The issue is that when no version is provided in the request any of the actions in the 1.0 controller that don't have an implementation in the 2.0 controller return a 400 because the metadata on the action processed by CurrentImplementationApiVersionSelector has both versions.

Is there an existing convention or convention I can remove to make only actions that share the same url template be considered when adding implementated versions metadata? Or would it be reasonable to make the CurrentImplementationApiVersionSelector smart enough to find the actual route of the highest versioned implementation of an action?

Also, I'm using the MVC library, but setting the controllers up via MapControllers in UseEndpoints. It's not clear from the current examples if that is a valid use-case, or which library it should use. So maybe the implementation specifically for endpoints could be used to do this?

.net version: net60
Libraries: Asp.Versioning.Mvc, Asp.Versioning.Mvc.ApiExplorer 6.3.1
Service set up code

        services.AddApiVersioning(config =>
            {
                config.DefaultApiVersion = new ApiVersion(0, 9);
                config.ApiVersionReader = new QueryStringApiVersionReader();
                // If the API version not defined in the request, most recent version will be assumed
                config.AssumeDefaultVersionWhenUnspecified = true;
                config.ApiVersionSelector = new CurrentImplementationApiVersionSelector(config);
                // Add response headers to report available versions
                config.ReportApiVersions = true;
            }).AddMvc().AddApiExplorer(config =>
            {
                config.ApiVersionParameterSource = new QueryStringApiVersionReader();
                config.FormatGroupName = (string groupName, string _) => groupName;
            });

App set up code

        app.UseHttpsRedirection()
            .UseStaticFiles()
            .UseRouting()
            .UseCors()
            .UseResponseCaching()
            .UseAuthentication()
            .UseAuthorization()
            .UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });

[commonsensesoftware]

Asp.Versioning.Mvc is the correct library for MVC Core. UseEndpoints is always called, but the latest example no longer shows that because in the most recent ASP.NET Core templates, that ceremony has been removed. It would appear you are upgrading from an older configuration or electing to use the older style setup. Regardless of the style you choose, the support is the same.

Supporting legacy clients that are not API version-aware is a certainly a supported scenario. I'm not sure why you would want to use CurrentImplementationApiVersionSelector in this case (and, honestly, in just about any scenario). What I'm not sure I follow is how a client would possibly know to ask for a resource that would possibly match to 2.0 (as you seem to describe). Moving the current, assumed version to 2.0 will definitely make that happen, which is why it doesn't really make sense. LowestImplementedApiVersionSelector would be a better choice or, better still, just use the DefaultApiVersionSelector (the default) and set the DefaultApiVersion to the default version that should be assumed. That appears to be 0.9, but if isn't, then ConstantApiVersionSelector will work if you pass it 1.0. That version will always be assumed when no version is provided. Again, a client bound to the implicit 1.0 shouldn't know how to ask for any other version.

Aside: config.FormatGroupName = (string groupName, string _) => groupName; is not going to do what you think it will. This callback will never be invoked with this setup (or it's not supposed to be). If you specify [ApiExplorerSettings(GroupName = "MyApi")], the value of "MyApi" will be retained. Similarly with no group, then just the formatted API version is used. If, and only if, you specify a custom GroupName and you specify FormatGroupName, the callback is invoked with the group name and formatted API version. The whole reason it behaves that way is so you don't have to define a callback like this to retain just the group name.

[commonsensesoftware]

You also don't need to explicitly set config.ApiVersionParameterSource. While this can be changed, ApiVersionParameterSource is implicitly configured to use what was defined for ApiVersioningOptions.ApiVersionReader.

[npbenjohnson]

I think this may just be a larger misunderstanding on my part of of how versioning works, and there will possibly be an usse with both LowestImplemented and CurrentImplementation.
I thought a scenario like this:

Controller (version 1):
Action - GetFoo
Controller (version 2):
Action - GetBar

With CurrentVersionSelector Controller/GetFoo would see the most current implementation of GetFoo is version 1 and call that endpoint, but the behavior I'm seeing is that tries to call it on the version 2 controller. I'm assuming that Lowest implemented would have the opposite problem and if I tried to call GetBar, it would use version 1 and error out. So mostly I'm just asking is there a set up that can find the latest version an action is implemented in instead of just assuming it is implemented in all versions?

Thanks for the other info btw, I didn't change the startup type in net50 because the web testing host wouldn't work with a program startup, I'm not sure if it's been fixed yet. I'll have to look more into grouping, I think that was in to fix something unexpected with swagger that ended up actually being a different issue.

[commonsensesoftware]

It's probably worth detailing how collation works. At the end of the day, it's not about controllers (or even endpoints), it's what's mapped over the wire.

You didn't provide any additional information, but let's consider:

namespace V1
{
    [ApiVersion(0.9, Deprecated = true)]
    [ApiVersion(1.0)]
    [Route("[controller]")]
    public class Foo : ControllerBase
    {
            [HttpGet]
            [MapToApiVersion(0.9)]
            public IActionResult GetV0_9() => Ok();

            [HttpGet]
            public IActionResult Get() => Ok();
    }
}

namespace V2
{
    [ApiVersion(2.0)]
    [Route("[controller]")]
    public class Foo : ControllerBase
    {
            [HttpGet]
            public IActionResult Get() => Ok();

            [HttpGet("{id}")]
            public IActionResult Get(string id) => Ok();
    }
}

API versions are collated by name (e.g. the logical API). While it's true, you can technically version all the way down to an endpoint, in practice, no one does that. When we talk about the Orders API or the Weather API, we are referring to a set of endpoints that make up an API (even if there is just one). This is one reason why collation is done by name. The more technical reason, however, is that there really isn't any other way to do it. You might think you can collate by route template, but there is a lot of idiosyncrasies. Consider order/{id} and order/{id:int}. These are semantically equivalent, but they are not the same. Attempting to interpret the meaning doesn't lead anywhere good. What happens when you have something like order/{id}/items or order/{id}/customer? Is that the Orders API? Maybe. It could equally be another API. Long story short, there isn't a good way to interpret the meaning. Controllers intrinsically represent a logic collection of actions for an API, so grouping that way is typically easy for people to rationalize.

Given the above configuration, the API name is Foo and all endpoints mapping to Foo are collated. It's also important to note that other criteria such as HTTP method are not considered. It is expected that 405 will be returned for an API that supports a version, but not that specific HTTP method.

URL	Action
foo?api-version=0.9	V1.FooController.GetV0_9()
foo?api-version=1.0	V1.FooController.Get()
foo?api-version=2.0	V2.FooController.Get()
foo/42?api-version=2.0	V2.FooController.Get(string)

The collated set will be 0.9, 1.0, 2.0. Deprecated doesn't mean unsupported; it's still implemented. Deprecated just means it will go away at some point. This can be more explicitly defined through a Sunset Policy to indicate when exactly it will be dropped.

A legacy client doesn't know to include api-version. Let's consider that they ask for:

GET foo HTTP/2
Host: localhost
Accept: application/json

If you use CurrentImplementationApiVersionSelector, then 2.0 will be selected because that is the current (or maximum) implemented version for the Foo API. If you use LowestImplementedApiVersionSelector, the 0.9 because the is the lowest implemented version for API Foo. Usually the lowest implemented API version is the original version and would work for the assumed default, but it doesn't have to be. Since you've set DefaultApiVersion = new(0.9), then the best option is to use ApiVersionReader = new ConstantApiVersionReader(new ApiVersion(1.0)). This will mean that 1.0 is used regardless of the available options. As long as you've properly mapped your legacy surface area to 1.0, all requests without an API version will route to the correct endpoint. This has the added benefit that if clients become version-aware, they can start with ?api-version=1.0 and still get the same behavior as if they weren't specifying it.

Ultimately, the legacy client doesn't know or understand anything about a version. It likely doesn't even know that it can move to another, explicit version. As the server, you just need to choose what you want to call this initial, default, implicit version. If that is 1.0, no problem. All mappings should line up endpoints for 1.0 to satisfy that requirement. In the simplest solution, you don't have to anything more. The DefaultApiVersion defaults to ApiVersion.Default, which defaults to 1.0. ApiVersionSelector defaults to DefaultApiVersionSelector, which always returns DefaultApiVersion. It's fine to change these, just know the potential side effects. 😄

[npbenjohnson]

I think that makes sense. I still don't know how my original ask would be supported, but I now understand why the way I was trying to use it is an edge case that isn't very important. I think I was basically hoping to abuse versioning where declaring groups for each segment of the legacy apis was more appropriate.

This still might technically be a bug in the expected behavior of CurrentImplementationApiVersionSelector since it effectively breaks any action that stops being implemented in the latest version of an api. But maybe it's just semantics and I was misreading "Current Implementation (of Api) Version Selector" as "Current Implementation (of action) ApiVersion Selector" because ApiVersion is generally used to mean Version in this library.

Either way, thanks for the explanation, this is way more clear now.

[commonsensesoftware]

The versions of an API are asymmetrical by default. For example, the Orders API might support 1.0 and 2.0 and the Customers API might support 2.0 and 3.0. You typically want that so that APIs can evolve independently. The term current [or lowest] implementation is meant to convey the implementation of the target API, not the entire application. Achieving that is possible, but it is a bit different. I refer to that as symmetrical versioning (e.g. you want all APIs in the application to have the same version set). There have been many threads about it, but the discussion in #900 will walk you through a foundation of how to achieve it (assuming that's what you're looking for).