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!