How to get rid of route-name conflicts when ensuring api works both with and without the api-version?

Question

I want to apply asp.net api-versioning to my web app (which didn't have versioning). However, the tricky issue is that I must ensure that APIs should work both with and without the api-version.

    [ApiVersion("1.0")]
    [Route("api/products/{productId}/[controller]")]
    [Route("api/v{version:apiVersion}/products/{productId}/[controller]")]
    [ValidateModel]
    [Produces("application/json")]
    public partial class ProductController : ControllerBase {

        internal const string GetLatestRoute = "GET Product/GetLatestAsync";

        [HttpGet(Name = GetLatestRoute)]
        public async Task<IActionResult> GetLatestAsync() {
        
        }
    }

I have a controller with multiple actions, each of them is defined with a unique route name. When I add two routes (with and without versions) to the controller, there comes a route-name conflict error:

Attribute routes with the same name 'GET Products/GetLatestAsync' must have the same template:

Action: 'Service.Controllers.ProductController.GetLatestAsync (ProductFD)' - Template: 'api/products/{productId}/Product'

Action: 'Service.Controllers.ProductController.GetLatestAsync (ProductFD)' - Template: 'api/v{version:apiVersion}/products/{productId}/Product'

There are several answers on StackOverflow that say the issue can be solved by removing the route names defined for the action methods. However, in my scenario, the route names are used to create Url Links in several places in the project.

Is there an approach that I can get rid of the issue? I'm wondering whether I could append version to the route name variable or mapping the non-version api to the version/1.0 ...? On the other hand, there is a rare case that I update all the methods in a controller. So is it possible that I only define a route-prefix on the top-level of the controller and only apply the api-version on the method-level?

Answer 1

Route names and the route table are not API version aware. In order for this to work, you need to use double route registration like you have because you are versioning by URL segment (not recommended). If clients are properly following the links returned by the server, then always using the route generated with the explicit version in it will do. If the client doesn't honor that and just calls the APIs directly without the API version, the second template will handle that for you. If you are only generating links with the same controller, then I would suggest using CreatedAtAction instead because it will not rely on the route name. If memory serves me correct, you can specify the order of each [Route] for precedence. If unspecified, it will be the first attribute specified - which matters.

You'll also need to enable:

services.AddApiVersioning(options => options.AssumeDefaultVersionWhenUnspecified = true);

If you haven't already.

Last, but not least, beware the known, breaking change: Async suffix trimmed from controller action names. This has snared many people.