In recent months it has become clear to me that the largest Web companies have become quite serious about providing "web platforms"that Web developers can integrate with or build upon. Amazon (http://aws.amazon.com), Google (http://code.google.com), Yahoo (http://developer.yahoo.com) and Microsoft (http://dev.live.com) all provide online destinations where Web developers can learn how to use their Web services or integrate with their AJAX widget platforms. The problem with building a platform is that providing Web services and writing APIs is the easy part. The hard part is hard work of supporting developers who have built on your platform with proper documentation, prompt tech support, and ensuring backwards compatibility when new revisions of the platform are delivered. Today I feel like riffing on that last point; versioning and backwards compatibility.

Maintaining backwards compatibility and being mindful of forwards compatibility is one of the biggest design problems that faces platform vendors. So far, there have been numerous examples of Web companies that provide APIs failing to realize how important stability and backwards compatibility when providing a platform. I've seen numerous examples of breaking changes in APIs providing by Web companies including the Google Adwords API (shutting down old endpoints with new version), TypePad Atom feeds (switching the feed format to a new incompatible version thus breaking feed readers), del.icio.us API (changing the Web service URL and the security protocol) and Amazon Web Services (changing what is added to a shopping cart when an item is added via its Amazon specific ID) among many others. Some of these changes were necessary due to security concerns while others could have been prevented with better up front design and decision making by the platform vendor. However in all of these cases, developers that had taken a bet on the platform had to scramble to check that their applications still worked and patch/redistribute them if they didn't. That is bad. One of the primary goals of a platform vendor is to ensure that the lives of developers on their platform is as easy and smooth as possible. This means releasing a new version of the platform should not cause developers who have taken a bet on the platform to have to rewrite their code.  

In the past I've written lengthy, and fairly complex articles about versioning and XML data formats. These days, I've boiled down my guidance on Web service versioning to one phrase; Cool URIs Don't Change. This simple philosophy is actually all you need to consider when designing your RESTful Web service. You apply it in the following way

1. The Web service end point (i.e. URL) should not change. Changing the actual service end point is bad (e.g. http://del.icio.us/api/posts/get to https://api.del.icio.us/v1/posts/get) instead you should design your URI space with the knowledge that there will be multiple versions of the protocol.
   
2. The types of messages returned by the end point should not change. Thus changing the data format of the service (e.g. changing from RSS to Atom or Atom 0.3 to Atom 1.0) is a bad idea. Thus you should have a strategy for supporting multiple formats and partition your URI space accordingly.
   
3. The behavior of the end point should not change. This is the trickiest one to follow but the one that your developers will appreciate the most. New versions of the API should not change the behavior of operations previously defined at that end point. One way to reach this ideal is to partition your URI space in a versioned manner (e.g. http://www.example.com/api/v1/get-stuff in version 1 and  http://www.example.com/api/v2/get-stuff in version 2) and then never change the behavior of the old bits or at the very least keep that behavior around as long as possible.
   

That's it. That's all you really need to know about versioning and REST Web services. The rest is mainly finicky details that are primarily dependent on the specifics of the platform  and the ease with which the developers on the platform can respond to breaking changes. The harder it is for them to change, the higher the bar should be for breaking changes. For example, for Windows Live Messenger we have a high bar for breaking changes in the protocol that the server uses to talk to the desktop client because we know for a fact that not only does it take a surprisingly long time for the majority of users to switch to a new version of the client, there are users who actually cannot upgrade for a variety of reasons (e.g. new versions of desktop client doesn't work on their OS, corporate users or students who can't install software on the PC without permission, etc). On the other hand, when it comes to the internal SOAP APIs that are used to communicate between the Contacts platform and Windows Live properties such as Windows Live Spaces, Windows Live Hotmail and so on the bar for breaking changes is slightly lower because (i) they are Web applications and the (ii) set of consumers of the API is limited.

Ensuring that a Web platform has a strategy for handling backwards compatibility issues is just as important in the Web 2.0 world as it is on the desktop. Platform vendors who think otherwise are in for a rude awakening if they want adoption of their Web platform by serious developers.