When Should I Version My OData Service?
While researching an answer a forum post on versioning, I was digging into one of the v1 product specs and found a couple of very useful logical flowcharts that describe how to handle data service versioning scenarios. Sadly, this information has yet to make it into the documentation. I will do my best in this post to distill the essence of these rather complex flowcharts into some useful rules of thumb for when to version your data service. (Then I will probably also put this information in the topic Working with Multiple Versions of WCF Data Services.
Data Model Changes that Recommend a New Data Service Version
The kinds of changes that require you to create a new version of a data service can be divided into the following two categories:
- Changes to the service contract—which includes updates to service operations or changes to the accessibility of entity sets (feeds)
- Changes to the data contract— which includes changes to the data model, feed formats, or feed customizations.
The following table details for which kinds of changes you should consider publishing a new version of the data service:
Type of Change |
Requires a new version |
New version not needed |
| Service operations | • Add new parameter • Change return type • Remove service operation |
• Delete existing parameter • Add new service operation |
| Entity set permissions | • Restrict entity set permissions • Change response code (new first digit value) | • Relax entity set permissions • Change response code (same first digit value) |
| Entity properties | • Remove existing property • Add non-nullable property • Change existing property | • Add nullable property* |
| Entity sets | • Remove entity set | • Add derived type • Change base type • Add entity set |
| Feed customization | Change entity-property mapping |
* You can set the IgnoreMissingProperties property to true to have the client ignore any new properties sent by the data service that are not defined on the client. However, when inserts are made, the properties not sent by the client (in the POST) are set to their default values. For updates, any existing data in a property unknown to the client may be overwritten with default values. In this case, it is safest to use a MERGE request (the default). For more information, see Managing the Data Service Context (WCF Data Services).
How to Version a Data Service
When required, a new OData service version is defined by creating a new instance of the service with an updated service contract or data contract (data model). This new service is then exposed by using a new URI endpoint, which differentiates it from the previous version.
For example:
- Old version: https://myhost/v1/myservice.svc/
- New version: https://myhost/v2/myservice.svc/
Note that Netflix has already prepared for versioning by adding a v1 segment in the endpoint URI of their OData service: https://odata.netflix.com/v1/Catalog/
When you upgrade your data service, your clients will need to also be updated with the new data service metadata and the new root URI . The good thing about creating a new, parallel data service is that it enables clients to continue to access the old data service (assuming your data source can continue to support both versions). You should remove the old version when it is no longer needed.
Cheers,