OData Protocol Transitions

One of the primary reasons to version a service is to facilitate changes in behavior and/or data exchange with the service. In the scope of OData, this can mean transitioning new versions of a service to use the OData protocol or it can mean existing OData services that are transitioning away from the OData protocol. The API versioning support for OData enables both of these scenarios.

Consider the following partial controllers implementations:

[ApiVersion( "1.0" )]
public class OrdersController : ApiController
{
    public IHttpActionResult Get() => Ok();
}

[ApiVersion( "2.0" )]
[ControllerName( "Orders" )]
[ODataRoutePrefix( "Orders" )]
public class Orders2Controller : ODataController
{
    [ODataRoute]
    public IHttpActionResult Get() => Ok();
}

[ApiVersion( "3.0" )]
[ControllerName( "Orders" )]
[RoutePrefix( "api/orders" )]
public class Orders3Controller : ApiController
{
    [Route]
    public IHttpActionResult Get() => Ok();
}

This set of controllers produce the following semantics for the Orders service:

• Version 1.0 of the service uses basic REST semantics and convention-based routing
• Version 2.0 of the service switches to the OData protocol and convention-based routing
• Version 3.0 of the service switches back to basic REST semantics and attribute-based routing
  • Note: The ControllerNameAttribute is applied because the inferred controller name Order3 will not match the lower versions of the service which are convention-based

The configuration required to support this type of scenario will be:

configuration.MapHttpAttributeRoutes();
configuration.AddApiVersioning();
configuration.EnableCaseInsensitive( true );

var modelBuilder = new VersionedODataModelBuilder( configuration )
{
    ModelBuilderFactory = () => new ODataConventionModelBuilder().EnableLowerCamelCase(),
    ModelConfigurations = { new OrderModelConfiguration() }
};
var models = modelBuilder.GetEdmModels();

configuration.MapVersionedODataRoutes( "odata", "api", models );
configuration.Routes.MapHttpRoute( "orders", "api/{controller}/{id}", new { id = Optional } );

You can see a complete end-to-end implementation of this scenario in the advanced OData Web API sample.