📣 Extra! Extra! Read all about! 📰

You've all been waiting a long time, but the release is nigh. As expected, supporting OData 8.0 was a complete rewrite. I applaud the OData team for properly supporting Endpoint Routing by computing the OData route templates upfront 👏🏽. Their solution was different, but fundamentally used the same concepts API Versioning was using. I'm certainly happy to ditch all that code because I never wanted to own it.

Despite asking for it, no hook or extension point was ever provided that would enable an EDM per API version design. The example @jfshark linked to does show something working, but it's very prescriptive and highlights the need for multiple EDMs per prefix. Restricting the options to only a prefix is infeasible; especially, since versioning by URL is not RESTful. A number of the internal OData types weren't doing me any favors either. If that weren't enough, the OData 8.0 libraries support OData 4.01 which has protocol-level changes that few probably have realized. Those changes certainly have effects on the API Explorer.

In spite of these challenges, I've finally been able to create a workable solution. In its simplest form, the configuration is simply:

services.AddControllers().AddOData();
services.AddApiVersioning().AddOData();

This might not look like enough, but it is. Remember that API Versioning provides IModelConfiguration to configure an EDM for each API version. As long as there are 1+ API versions, an EDM can be created for each version without a prefix and, hence, no additional configuration. If you do want a prefix, it's as simple as:

services.AddControllers().AddOData();
services.AddApiVersioning().AddOData( options => options.AddRouteComponents( "api" ) );

Notice that you configure the API Versioning options and not the default ODataOptions. This is how the two pieces are separated. ODataOptions can be used to configure everything except RouteComponents. Think of them as a template. If you do attempt to configure ODataOptions.RouteComponents or ODataOptions.AddRouteComponents, they are simply ignored. Similarly, ODataApiVersioningOptions.AddRoutComponents does not directly expose or accept an IEdmModel, but it does have parity with all of the other OData configuration options. If you prefer not to use IModelConfiguration, the VersionedODataModelBuilder will now be exposed via ODataApiVersioningOptions.ModelBuilder. For example, you could have:

services.AddApiVersioning()
        .AddOData( options =>
        {
            options.ModelBuilder.DefaultModelConfiguration = ( builder, apiVersion, prefix ) =>
            {
                // inline model configuration
            };
        } );

The other parts and design of VersionedODataModelBuilder remain unchanged from previous versions.

Now, I know what you're thinking, "That's great, but I need OpenAPI support too." Let me answer your 🙏🏽🙏🏽🙏🏽. The refactored implementation for the API Explorer now supports OData 8.0 too! In its simplest form, the configuration might look like:

services.AddControllers()
        .AddOData( options =>
        {
            options.Count().OrderBy().Select();

            // not strictly necessary, but pairs down lots of route forms that you
            // are probably not interested in
            options.RouteOptions.EnableKeyInParenthesis = false;
            options.RouteOptions.EnableNonParenthesisForEmptyParameterFunction = true;
            options.RouteOptions.EnableQualifiedOperationCall = false;
            options.RouteOptions.EnableUnqualifiedOperationCall = true;
        } );
services.AddApiVersioning()
        .AddOData( options => options.AddRoutComponents( "api" ) );
        .AddODataApiExplorer( options =>
        {
            options.GroupNameFormat = "'v'VVV";

            // configure query options which cannot otherwise be configured by OData conventions
            options.QueryOptions.Controller<V1.PeopleController>()
                   .Action( c => c.Get( default ) )
                   .AllowOrderBy( "firstName", "lastName" );
        } );

At this point, you're probably overwhelmed with excitement 😹 and you're thinking, "Show me the code!". You need look no further than the all new and updated OData examples here.

The final, but million💰💰💰 question is, "When can I get it?". Soon. 😉 Be sure to follow the recent announcement as well as the 6.0 roadmap. This actually just the tip of the iceberg. There's many more great features queued up for the 6.0 release too. As soon as I'm able to sort out all the package publishing tasks, I plan to get a pre-release out straight away. If you just can't wait, the code is there for you to play with. I really hope some of you try it out. I'd love to hear feedback and any issue you might find; particularly in the OpenAPI area. The coverage is solid, but OData has a very big test matrix for features, which is difficult to facilitate with just one person.

Enjoy! I'm looking forward to getting this out to you all ASAP.

Support for OData 8 #677

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions