AspNetCore api Versioning MapToApiVersion not descovered but still able to hit the route

Question

Please consider the following case.

Because version 1.0 is not defined on the controller in a ApiVersionAttribute it is not discovered a not declare an API version. Just like i want because from this moment on i don't want to support this version any longer. My swagger documentation that is dependen on the IApiVersionDescriptionProvider works correctly and is no longer generating documentation for version1. When i make a api call to version 2.1 and check the returned version headers there is also only the supported version 2.1 & the deprecated version 2.0. Just as excpected.

But when i make a call to version 1.0 i still hit the endpoint and the apiversion still doesn't return 1.0 as a supported version. I was hoping this would return a 400 bad request with the "UnsupportedApiVersion" error message and with the headers descriping the versions 2.0&2.1.

The reason i was exploring this behavior is that we want to make it possible to upgrade our microservice versions through adding the ApiVersionAttribute for certain version at runtime through some configuration. So we don't need to make a new build because the Getdefault route will be mapped for those higher apiversions.

//  Declare both versions
[ApiVersion("2.0", Deprecated = true)]
[ApiVersion("2.1")]
[Route("v{version:apiVersion}/HelloWorld")] // Support path versioning
[ApiController]
public class HelloWorldController : ControllerBase
{

    //  Map to v1.0
    [MapToApiVersion("1.0")]
    public string Get1() => "v1.0";

    //  Map to v2.0
    [MapToApiVersion("2.0")]
    public string Get2() => "v2.0";

    //  Map to all versions defined on the controller that not already have a mapping
    public string Getdefault() => $"{forExamplePerposeHereIsVersionReturned}";
}

(package used Microsoft.AspNetCore.Mvc.Versioning)

Thanks for any input!

Answer 1

This is happening because a route still exists for v1.0/HelloWorld and Get1 maps to this version. API Versioning doesn't change routing, it merely allows matching and disambiguating otherwise duplicate routes by API version metadata. Although 1.0 is no longer declared, the fact that a valid route still exists for it and maps to the corresponding version results in a match.

The proper way to remove this API/action when it is no longer valid would be to remove the action (e.g. the code). That is the default expectation.

There are a couple of approaches that are possible to make things appear dynamic. You could use custom conventions to only declare and/or map API versions based on some type of configuration. This can be done with the API Versioning Conventions API or you can add your own custom convention. Another approach would be to register a custom IActionDescriptorProvider that runs last and removes the ActionDescriptor for APIs that no longer apply by inspecting their associated version information. This information is retrieved by getting the ApiVersionModel via the ActionDescriptor.GetApiVersionModel extension method.

---

UPDATE: While this is the behavior, it was actually a bug. An API version that is only mapped should not be routed.

The bug was reported in Issue 735. In Microsoft.AspNetCore.Mvc.Versioning 5.1, the response will now be 400. In Asp.Versioning.Http or Asp.Versioning.Mvc, the response will be 404.