Craigs Blog

Lunchtime at work and just researching so thought I’d note down some of my findings. Well I’ve written and read a fair bit about web services lately and you can read some of my links on the subject of soa here. It occurred to me that while I have experience (positive at that) in writing, using, monkeying around with SOAP based RPC style services I haven’t got any in REST services – in spite of my growing support for that approach. So what exactly would a good REST interface look like?

Well off to google I went and you can see some of my findings at that del.icio.us link but I figured a list of links won’t help me recall my thoughts or where things were or what I thought was useful. So here I am writing about it in my lunch time.

• The RESTfulDesign article on this REST wiki is a good start, some handy hints. I must admit I like UML sometimes but actually doing detailed modelling in UML isn’t my idea of fun – I have a tendency to get to a high or medium level model, generate some code if I can and then code it and reverse engineer the detailed models if required. Side point really but a good step by step guide.
• This REST mistakes article gives the negative view of the REST approach and design principles. Reading through this and other less well written articles I started to form a view that these principles were opinion rather than written in stone, and arguably many design principles are just that.
• There appears to be a book in the making here too.

So I figure what interfaces are out there that are good.

• The Amazon web services site is quite impressive with an interesting array of services (er, not like SOA services, like stuff they offer ;) ) which actually should form the subject of a future blog entry. Anyhoos there are some links here for you to enjoy. I found aws zone’s tools really useful in understanding what the REST services look like and indeed the SOAP ones too. Enjoy. key point seems the aws stuff actually deviates from the above guidelines around URIs. The data’s all in the URI but only in the query string, I don’t think thats strictly speaking a good RESTy design. Saying that its live and heavily used so… – example URI: http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&SubscriptionId=[Your Subscription ID Here]&Operation=ItemSearch&Keywords=[A Keywords String]&SearchIndex=[A Search Index String]&Sort=[A Sort String]
• Amusingly the very tool I use to keep links has an API – there’s an article on the del.icio.us API which I’m reading that looks quite good. Of course the URI used on the first page annoyed me somewhat – https://api.del.icio.us/v1/tags/get – you’re calling it with a HTTP GET request!!! tsk. An interesting example of having the version number of the API encoded in the URI though and apart from the extraneous ‘get’ on the end it didn’t worry me. What did worry me was that you HTTP GET requests to change things in the system – a GET request to this URI https://api.del.icio.us/v1/tags/rename?old=Rails&new=rails would change the name of the tag which kind of doesn’t sit well with the idempotency (i.e. the second time you call it it’s technically an error condition) of the GET request. This URI gives you an insight into the URI structure by the way – version/resource/action?arguments. Gotta admit thought that the Ruby code to use the API to change the case of your del.icio.us tags is quite neat. Link to the del.icio.us api help page here.
• This search functionality was cited as an example of a REST interface and while its using URI’s and isn’t SOAPy and is HTTP etc. here’s how you retrieve a document from this: http://www.dlese.org/dds/services/ddsws1-1?verb=GetRecord&id=DLESE-000-000-000-001. So, query strings and using verbs and have the word get in the URI – the latter is swiftly becoming a bug bear of mine.
• Now this page on the sqlrest project seems to describe a system based on what I’ve read of REST. Of course, its just a framework, isn’t an API (and there fore possibly doesn’t belong here) and actually doesn’t deal with RPC style stuff. At least it does respect the HTTP verbs though.

Summary then? There are non-SOAP API’s out there that are using URI’s and HTTP to great success. Enterprises still prefer SOAP it seems, well thats my experience. However, there is far wider adoption of call this URI style interaction. As for REST APIs that meet the docs cited at the top I couldn’t seem to find any that were used in earnest. Most articles seem to suggest a mix of REST services and RPC style services is common it seems even simple applications (ish) like del.icio.us didn’t opt for or didn’t understand a full REST approach and went more RESTish instead. In truth, just assembling appropriate URIs appears to be a very easy way to get applications talking – perhaps my hang up regarding GET not changing the resource (as per the spec!) actually makes the interface hard enough to use that people wouldn’t? Deserves more thought.

Actions outstanding? Still need to find a good SOA definition or write one and put it here and now I’d like to actually find an application and put together a good REST design for it.

PS: quick note on the Amazon API

Similarly, Amazon.com’s web services are provided in two forms: one adhering to the formalisms of the SOAP (Simple Object Access Protocol) web services stack, the other simply providing XML data over HTTP, in a lightweight approach sometimes referred to as REST (Representational State Transfer). While high value B2B connections (like those between Amazon and retail partners like ToysRUs) use the SOAP stack, Amazon reports that 95% of the usage is of the lightweight REST service.

From: http://www.oreillynet.com/lpt/a/6228