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.
The kinds of changes that require you to create a new version of a data service can be divided into the following two categories:
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
• Add new parameter • Change return type • Remove service operation
* 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).
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:
Note that Netflix has already prepared for versioning by adding a v1 segment in the endpoint URI of their OData service: http://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.