There’s an interesting discussion going on at The Wisdom of Ganesh in which Ganesh Prasad and “Integral ):( Reporting” (presumably the “JJ Dubray” mentioned in the article) are trying to work out some issues around versioning, REST and SOAP. This post is also referenced and commented on at infoQ.
In the 14th comment to the original article, JJ calls for a real-world example – this is a good idea which should help ground the discussion and diffuse the temptation to communicate in abstract principles. In the spirit of this request, I will describe an example based on problems I faced in a previous job.
The first version of the system we were working on consisted of a server component, coded in Java, which provided remote services to several client systems. Each of the client systems was a Java web application, responsible for providing customer-specific web pages and navigation using the services and content provided by the central server. For some customers there would be just one instance of the web client, for others with greater load there would be several.
The server system was responsible for managing products for sale, including descriptions in multiple languages, format and compatibility meta-data, thumbnail images in several sizes, prices in multiple currencies. As well as access to individual items and collections, a search facility provided a way to discover or look up products. The server also managed customer details and purchase histories, and handled both delivery of content and general messaging (by email and SMS) during the purchase process. The client systems were responsible for display and navigation of a product catalogue, customer branding, “shopping cart”, login/logout, and everything else a user experiences.
The API between client and server included ways to list products by category, fetch details of specific products, search using a variety of criteria, make and cancel purchases, fetch and update user data and so on.
I suggest this should be a reasonable system on which to base a discussion – it embodies similar concepts to many other systems, and is neither trivial nor impossible to build. Interestingly, both SOAP and REST versions of the interface between the clients and the server were implemented at different points in the life of the product.
So, on to versioning. It seems to me that there are several kinds of changes which might require versioning. I will list a few here, but I welcome suggestions for others I might have missed.
- The first deployment of the system worked with only a single currency. The move to multiple currencies was a potentially major change in the interaction between client and server, even though each client works only in a single currency.
- The customer for one client implementation required the provision of extra services, specific to their market, which were not required by (and should not be available to) other clients.
- The initial version of the search facility returned data for all matches, with paging through the results implemented entirely on the client. When there was a lot of data in the catalogue this became an unacceptable performance bottleneck, especially as results beyond the first few pages were hardly ever viewed. An alternative approach was suggested where a client would request a specified page (of a specified page size) from the search results. This required changes in both the search request and search results.
- A new source of products introduced the idea of collections. Items in a collection could be purchased individually or as a bundle. Viewing a collection while browsing, searching, or in a user’s purchase history, should allow a user to “drill in” to the collection to view the items within it. Items located while searching should indicate how to purchase the collection, as well as how to purchase the individual item.
Is this a useful amount of detail for a scenario? I have my own experiences of working with this system and the choices we made, but I’d love to read any suggestions for how you might handle any of the transitions above in a live system with multiple client systems deployed, many of which can not be changed easily or often, and a server full of historical purchase data. Procedural remoting approaches (SOAP, XML-RPC and Java RMI etc.) and resource-based approaches (REST) are all welcome.