Thoughts on versioning data services

Today's post is about versioning data services. What is the most efficient way of evolving your OData system without sacrificing back compatibility?

Of course the answer depends on what is changing, so let's dig in a bit.

Let's say that data is changing. In this case, you might account for this in the model or only in the back-end. For example, implementating a log table is a common way of allowing data to "version" or maintain history. This isn't what I'd like to focus on today.

Let's say you make a schema change. In this case, you are probably best served by a new URL, if you can keep the old service running for back-compat (that is, if there isn't a fundamental change that requires rewriting all clients as well). By "a new URL" I mean having a new entry point, so for example you can have https://www.example.com/v1/service/ be the root of your service, then add new types and relationships and publish the service as https://www.example.com/v2/service/. If the old v1 service still runs, existing clients work with the server, and newer clients can migrate to v2 over time.

You may be able to get away with doing an in-place upgrade for some specific scenarios if you have control of the clients, for example adding a property to an entity when all clients disregard the new property and don't write data back in a way that would corrupt this new property. Or adding a completely new type of entity that isn't connected with the rest of your model; the metadata and service documents change, but old data is unaffected.

Finally, you might just be changing your server capabilities, for examply by upgrading to the latest version of WCF Data Services and enabling new features. This is the case that's typically handled with the data service version headers. In this case, the client and server negotiate how to interpret the contents of their communication. Many times these aren't a breaking change, in which case you can keep your URL; in other cases, you can use a new URL to expose the new capabilities, and leave the old service running for back-compat.

Enjoy!

Comments

• Anonymous
  April 12, 2010
  Another idea, if applicable, if you have an application serving this URL for data retrieval, you can simply add the version of the service required to run as a parameter to the service, instead of making it as a folder. This way, the clients, who are already using your URL, will not be affected, and you can later on add more services, versions as you like. Or perhaps, a client can easily change the service's version required in their call to your application.