Conrad Strydom views and commentary from a web engineer

A bit on RESTful webservices

Today I was put on the spot and asked to explain REST as it pertains to Web Services, unfortunately I found that I could not articulate that which I know and ended up basically flubbing the opportunity. Uggh, I was so angry at myself.

The truth is that REST is not easy to use and/or explain. Yeah, its simple but its not easy, in fact its hard. So I thought to avoid that particularly uncomfortable situation recurring that I should come up with some basic points to explain it, I shall call them Conrad's 4 basic cornerstones of RESTful Web Services. Those reading here should also see it as an opportunity to chime in and help by providing feedback as I think there are a lot of people that THINK they understand REST but don't really grok and I am certainly not excluded in that statement. I am not going to go into the benefits and what not, read wikipedia for that. This is purely some notes on the very basic principles.

Conrad's 4 Cornerstones of RESTful Web Services (HTTP)

REST = Representational State Transfer

1. The service exposes application state and interaction as resources that can be represented (sic) as a unique URI over HTTP
2. Resources are manipulated (maybe not the right word) through a uniform interface, these are POST, GET, PUT and DELETE verbs
3. The service is stateless.
4. The service is strictly client-server

Right I believe that is enough for my purposes, there are some other bits around Caching and Layering, mime types and response codes that my points don't cover but IMHO we are ok as HTTP takes care of that for us to some extend and the rest are less crucial to grokking the concept and thus removed for simplicity.  (opinions?)

What does the URI address for the resource look like?
A simple example:
http://mysite.com/api/user/1
Here we are addressing a specific resource in the user collection .. though we are not expressing any intent as we are not providing a verb.

Throw a verb in the mix:
GET http://mysite.com/api/user/1
Ah, now we are getting somewhere we want to retrieve the data for that specific resource.

OR

DELETE http://mysite.com/api/user/1
I would like to delete the addressed resource..

Similarly POST would create a new user (drop the resource identifier "1" here) and PUT would alter and replace the resource.

Thus the verbs loosly map as follows for out purposes:
POST = CREATE
GET = READ
PUT = UPDATE
DELETE = DELETE

Responses on these actions will return status codes, another handy HTTP freeby that REST can use e.g. 200 OK's and 404 Not Found etc..

To state or not to state?

Um REST is stateless and the so-called gray area of using cookies for auth purposes is not gray, its broken. Just deal with the fact that your are not 100% compliant and leave that there.  Alternatively look at Amazons Rest Auth implementation which operates via headers sent to and fro. Also adding the session identifier to every URL is not valid as this breaks the uniqueness of the resources' address as each user will utilise a different URI to address THE SAME resource!

Ok I am tired now, I still want to talk about using RESTlike URL's in your web application/site (as opposed to API's for webservices) as I have done in the past which raises issues such as the difficulties of using PUT and DELETE via browser forms often addressed by repurposing the POST method somewhat .. maybe subject matter for a next time.

PS whats up with Facebooks so-called RESTlike API?

Methods like admin.getAllocation etc??? Looks more like RPCLike what with method names getting sent in the requests? Use of HTTP and XML does not a REST service make!