Tesco.com API to become more RESTful

I've been won over in the face of some feedback from Tesco API developers: The Tesco.com Grocery API will retain its SOAP interface for communication with client applications but it's also going to get a REST interface too,very soon.

The Tesco API web service endpoint uses SOAP ('Simple Object AccessProtocol') which allows the full service description to be shown to clients in a long and complex XML document. This is no problem if you have Microsoft Visual Studio 2008 since a rather nice 'wizard' takes care of reading this XML configuration and creating lots of client-side code so that your .Net client application can use the web service easily.

However many other Integrated Development Environments do not have this Microsoft-borne luxury, not to mention that fact that some developers like to hand-craft their code directly. To these IDEs and developers, SOAP is a tall cliff to climb to get to configure our service with their client applications. Time and time again I get emails saying "Why can't you implement RESTful services for your API?".

So here I am this morning poring through the book "RESTful .NET" by Jon Flanders (O'Reilly publishing) and I suddenly understand why REST ("REpresentational State Transfer") is so popular: Whereas SOAP performs many actions from one web address (using complex XML documents to describe and access each action), REST's implementation of those same actions uses one-web-address-per-action. REST adopts the true name of a web address - a Uniform Resource Identifier - to describe each action.

Let me show you:

So, our SOAP service endpoint is all at:
http://tesco.cloudapp.net/TescoAPI.svc
...and interacting with all the methods and objects there takes sending and receiving XML documents to/from that service endpoint. Inspecting the web address above gives you no clue as to how to, for example, search for 'chocolate'.

Instead, REST simplifies this by accessing methods through the web address call itself. If I get the RESTful design right, searching for chocolate could be as simple as (contrived):
http://tesco.cloudapp.net/grocery/products/chocolate

To get to my favourite organic cider using its barcode could be:
http://tesco.cloudapp.net/grocery/products/5012845172809
...and anyone can type that manually into a web browser and get the same results as easily as a client application, albeit just data.

What about logging a customer in to get the search from their store? Simple. Just log the customer in using (note the secure 'https'):
https://tesco.cloudapp.net/grocery/login/customer-email&password

...to get a result back containing a unique session ID, e.g. "f7236grrg2g2rg7fg642", and then:
http://tesco.cloudapp.net/grocery/products/chocolate/f7236grrg2g2rg7fg642

Adding to a basket or updating the quantity? Just use the Product ID that is returned with any product search, plus a quantity (here I show a possible alternative, using a query string):
http://tesco.cloudapp.net/grocery/basket/add?id=f7236grrg2g2rg7fg642&productid=347373822&quantity=3

Delete from a basket (again using a query string but alternative syntax is available):
http://tesco.cloudapp.net/grocery/basket/delete?sessionid=f7236grrg2g2rg7fg642&productid=347373822

...and so forth (please remember these are contrived REST actions to show how much easier it is to understand).

Simple, straightforward, understandable - this is what REST offers and the more I read Jon Flanders book the more I have become a fan.

Once I have finished the book I'll go and do some design - but if you are already a seasoned REST developer and there is any direction you think I should go based on your experience I will be happy to listen - just email me at nick 'at' lansley dot com.