OData Versioned Metadata URL Path Versioning

[rossbuggins]

When using URL path versioning with OData, I'm having a problem configuring default version to load when no version is specified. The known limitations shows how to solve with attribute routing, but not for convention based routing for odata. I'm primarily after this so that the metadata can be accessed with an OPTIONS request with no version specified so as to find all API versions easily.

https://github.com/Microsoft/aspnet-api-versioning/wiki/Known-Limitations

[commonsensesoftware]

This is another example of why I loathe versioning by URL segment and illustrates why it's the least RESTful for all versioning methods; especially if all you want is OPTIONS support on the $metadata endpoint. All other methods of versioning just work for the same scenario.

In order to make your scenario work, you need to use double route registration just as you would with normal attribute routing. It should look like this:

services.AddApiVersioning(
    options =>
    {
        options.ReportApiVersions = true;
        options.AssumeDefaultVersionWhenUnspecified = true;

        // note: this is optional, but it will take away versioning by query string
        // the default behavior is a composite reader
        options.ApiVersionReader = new UrlSegmentApiVersionReader();
    } );

app.UseMvc(
    routeBuilder =>
    {
        // register routes with and without the api version constraint
        var models = modelBuilder.GetEdmModels();
        routeBuilder.MapVersionedODataRoutes( "implicit", "api", models );
        routeBuilder.MapVersionedODataRoutes( "explicit", "api/v{version:apiVersion}", models );
    } );

Now you'll be able to request api/foo and api/v1/foo with them going to the same place.

I hope that helps.

[rossbuggins]

Hi @commonsensesoftware, thanks for getting back to me. I'm getting the below exception when I put in the second MapVersionedODataRoutes().

Microsoft.AspNet.OData.Routing.UnversionedODataPathRouteConstraint.Match(HttpContext httpContext, IRouter route, string routeKey, RouteValueDictionary values, RouteDirection routeDirection) in UnversionedODataPathRouteConstraint.cs, line 54

Thanks, Ross

[rossbuggins]

Just had more of a look at this and you need to specifiy the explicit routes first, and then the implicit:

app.UseMvc(
    routeBuilder =>
    {
        // register routes with and without the api version constraint
        var models = modelBuilder.GetEdmModels();
        routeBuilder.MapVersionedODataRoutes( "explicit", "api/v{version:apiVersion}", models );
        routeBuilder.MapVersionedODataRoutes( "implicit", "api", models );
    } );

[rossbuggins]

I'm getting a problem with Swagger now - I'll ask on their issues page shortly, but in case you know a quick fix, what i really need to do is just exclude the "non versioned" url route from swagger documentation generation.

 An unhandled exception has occurred while executing the request.
System.NotSupportedException: HTTP method "GET" & path "api/v1/" overloaded by actions - TestingOdataApiVersioning.Controllers.CallsController.Get (TestingOdataApiVersioning),TestingOdataApiVersioning.Controllers.CallsController.Get (TestingOdataApiVersioning). Actions require unique method/path combination for Swagger 2.0. Use ConflictingActionsResolver as a workaround
   at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.CreatePathItem(IEnumerable`1 apiDescriptions, ISchemaRegistry schemaRegistry)
   at System.Linq.Enumerable.ToDictionary[TSource,TKey,TElement](IEnumerable`1 source, Func`2 keySelector, Func`2 elementSelector, IEqualityComparer`1 comparer)
   at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.CreatePathItems(IEnumerable`1 apiDescriptions, ISchemaRegistry schemaRegistry)
   at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.GetSwagger(String documentName, String host, String basePath, String[] schemes)
   at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
   at Microsoft.AspNetCore.Builder.RouterMiddleware.Invoke(HttpContext httpContext)
   at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]

[commonsensesoftware]

The issue in the UnversionedODataPathRouteConstraint is actually a bug. I stumbled across it myself, but it only appears to happen if the requested API version doesn't exist at all. This particular setup yields a NullReferenceException instead of 400. It will be fixed in an upcoming patch.

The order of route registration shouldn't really matter all that much. It may depend on other things you have configured. I tested the setup with the order I provided and it seemed to work just fine. If swapping the order works for you, that shouldn't be a problem.

I didn't try running through Swagger with this particular setup, but there will naturally be duplicate routes - one with and one without the API version. I wouldn't expect an exception in this case, just duplicate routes. I'll take a peek just to make sure. Regardless, if you want to remove a set of the routes, then you'll need either provide a custom IApiDescriptionProvider that filters results (this is what API Versioning provides and how Swagger gets its information) or you can provide a custom IOperationFilter (I believe) in Swashbuckle to omit generating certain actions. Either approach should get you the desired result.

[rossbuggins]

Hi, I've tried the IOperationFilter but this is not called until after the exception happens. Where is the IApiDescriptionProvider set please? Thanks, Ross

[rossbuggins]

I've sorted this with the below implementation, its working with versioned odatacontrollers and standard ones.

public class RemoveImplicitDefaultVersionedUrlRoutes : IApiDescriptionProvider
    {
        public int Order =>  -2000;

        public void OnProvidersExecuted(ApiDescriptionProviderContext context)
        {     
            //remove if not versioned
            var expli = context.Results.Where(r => !r.RelativePath.StartsWith("api/v")).ToList();
            foreach (var x in expli)
                context.Results.Remove(x);

            //remove any other duplicates
            var inThere = new List<string>();

            foreach (var x in context.Results.Distinct().ToList())
            {
                var es = x.EntitySet();
                if (es != null)
                {
                    var name = es.Name;
                    var version = x.GetApiVersion();
                    var method = x.HttpMethod;

                    var key = name + "_" + method + "_" + version;

                    if (inThere.Contains(key))
                        context.Results.Remove(x);
                    else
                        inThere.Add(key);
                }
            }
        }

and using it through standard DI

services.AddTransient<IApiDescriptionProvider, RemoveImplicitDefaultVersionedUrlRoutes>();

[commonsensesoftware]

It seems this is now resolved. Glad you got something working. Come back if you have more questions. Thanks.