Known Limitations

ASP.NET Web API Routing

The Direct Route routing mechanism (aka attribute routing) in ASP.NET Web API was bolted onto the existing routing infrastructure. The design of the out-of-the-box router does not account for nor support overlapping routes between convention-based and attribute-based routes. The result of this behavior is that for each given route, all of the versioned controllers must use convention-based or attribute-based routes. Mixing the two routing strategies for the same route is not guaranteed to resolve correctly.

While it would be ideal to implement a router that could support both approaches, the level of effort to achieve this is high. Furthermore, it's significantly easier to rationalize about versioned controllers from a service author's perspective if all of the versioned routes follow the same routing strategy.

OData Routing

The OData support for ASP.NET Web API uses convention-based routing under the hood. If you want to support transitioning to, or from, OData using API versioning, your ApiController types that match the same routes must also use convention-based routing.