A bit on RESTful webservices

February 10, 2009

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:
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.


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:

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!


5 Responses to “A bit on RESTful webservices”

  1. Dewald Botha Says:

    In theory rest seems like an easy solution, but if you are like me you’d prefer the soap/xml-rpc way of doing things.

    Okay, I know it is easy to just simply PUT something to an human readable URI, but what’s wrong with calling a function with xml-rpc/soap.

    Doesn’t it kind of keep the flavor going with the idea of using objects and functions.

    Well, thats just me.

  2. Conrad Says:

    IMHO the biggest difference between REST and RPC is that REST is noun based (don’t confuse with the HTTP verbs) and RPC is verb based.

    Example of REST noun interaction:

    vs RPC verb interaction
    getUser: 1

    The main difference here is that the REST implementation has a single unified interface to your objects (nouns) and is easy to use for developers when adding new objects etc.

    The appropriate verbs to use with RPC is not that obvious from the word go and the net effect of a particular action is not that clear either and may become ambigious. Anyhow .. just my 2 cents.

  3. Stii Says:

    Dewald, I think there is a quest for API and site to become one. I.o.w. if you have RPC web services you always have to maintain it separately to your site. REST allows you to sort of close that gap in that both human and machine can use the same thing.

  4. Dewald Botha Says:

    @Stii: Yip – i agree, but the problem I always found with REST is when you try to go too deep into the rabbit hole.

    Take for example a call where one would like to pull all users from a site with a user ID between 1 and 10, who has joined between 2008 and 2009 with the surname ‘DOE’.

    You could translate that into a REST URI, but it would end up probably being longer than the wall of China.

    I think one has too find a balance between using a stateless interface such as REST and something such as XML-RPC or SOAP.

    Maybe a RESTful SOAP service – ROAP. 🙂

  5. Stii Says:

    No, I hear you! REST is not a silver bullet. There are some instances (like your example) where it is not 100% practical.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: