7 mistakes explained on a single example…
RESTful web services seem to be gaining in popularity over SOAP / RPC oriented web services, but what is a REST (Representational State Transfer) service, really?
The term was coined by Roy Fielding in his Ph.D. dissertation in 2000, so it is not really a new thing. Some people like to wave the term around like a new mysterious tool that only the chosen ones can understand and wield. Some authors like to dance around the topic without getting down to the elevator speech description and go into great and elaborate examples on how “RPC is too complex in this or that scenario, and this is why you should use REST instead”. Cut to the chase already!
One book that do actually get to the point, is RESTful Web Services by Leonard Richardson & Sam Ruby (O’Reilly, ISBN 0-596-23926-0). Easy read, good examples, sensible commentary.
So… what is REST ?
Key: The URI is our permanent and unique key to the content
Content: Can be anything, really, as long as it can be sent across the transport
Transport: HTTP (Get, Put, Update, Delete)
Transaction: Always one complete operation per REST object
Ok, so that might be a tad oversimplified, but it actually isn’t much more complicated than that. In a way, you can compare it to a file system, and depending on how you build your content, it can be cached like a file system, in your ISPs cache, the company firewall cache, and your desktop browser cache.
Was that too easy? Well, there are some areas that are not quite as well defined, such as content description, content discovery, and access control – but there are more than one way to Rome here. Eventually, some sort of best practice will probably emerge, but right now it is sort of every RESTful service for itself.
IMO, for a developer – the true challenge with REST is deciding on how to construct your data URIs and how to partition up your data so that they are easily and logically accessible. You have to consider such stuff as categories, filtering, time range, wildcards, etc. If you intend to cache the data, you also need to figure out versioning so that you don’t get stuck with stale data. On the coding side – the real action happens behind the http transport on your server, where you have to do your stuff to pack and deliver or unpack and store your data.
It turns out that REST is not even a bit mysterious. Some people just like to pretend that it is. You don’t need huge commercial complex frameworks to write a REST service. Come to think of it, Delphi is a great tool to write REST servers in. It has all you need: good parsing tools, database integration, http components, etc.