RESTful Web Services

I recently started reading the O'Reilly book on RESTful web services, as the title suggest, by Leonard Richardson & Sam Ruby. The book is good, easy to read and pretty entertaining. I'm really bad with technical books because I get really bored really easily so I was pretty surprised that I've gotten as far as I have (which Isn't very far).

Ok now I'm going to go ahead and make a complaint about resource-oriented architecture. Please be advised that I have not read very far into the book so maybe this question of mine gets answered somewhere along the line. Also feel free to put me in my place if you think I'm terribly wrong.

Firstly, lets go ahead and give the definition of RESTful services as given by R&R. REST stands for Representational State Transfer. A RESTful web service is one where resources that are being sent back and forth in the service are defined and addressed in a very specific way. In particular, when a request is being made from a service it should correspond to a HTTP method that defines the action being performed on an associated resource at the server. The resource being affected should be identified using the URI. Those are basically the two main principals: actions must be associated with HTTP defined methods (GET, POST, PUT, DELETE, HEAD) and resources being affected must be identified in the URI. Simple enough.

In fact it is so simple that even I can go ahead and provide a simple example for you. Imagine I have a web service that provides to you information about books that I've read. By information I mean my comments on what I thought of the book.

Now imagine that the client interacts with my service in the following way:

• To get information about a particular book the client makes an HTTP GET request to the URI http://exmaple.com/getBook/. The body of the request contains some xml with the ISBN of the book that they're interested in. The response will be an xml document with the the comments about the requested book
• To update information about a particular existing book, the client makes an HTTP GET request to the URI http://example.com/updateBook/. The body of the request, again, contains some xml with the ISBN of the book that they're updating as well as the comments they want to replace with
• To delete information about a particular book, client makes and HTTP GET request to the URI http://example.com/deleteBook. The body contains the ISBN of the book they want to delete
• To add a new book, the clients makes an HTTP GET request to the URI http://example.com/addBook. The body of the request contains some xml with ISBN of the book being added and some comments that will be associated with it.

So that sums up our current service. This is not a RESTful service. It does not identify the resource (the book) that is affected in the URI, not does it use the HTTP methods to do corresponding actions. Lets make this a RESTful service then. We'll change it to do the following:

• To get information about a particular book the client makes an HTTP GET request to the URI http://exmaple.com/book/[Book ISBN]/. The body of the request doesn't have to contain anything. It can be empty. The response will be an xml document with the comments about the requested book
• To update information about a particular existing book, the client makes an HTTP PUT request to the URI http://example.com/book/[Book ISBN]/. The body of the request will simply contain the comments that we are replacing with
• To delete information about a particular book, client makes and HTTP DELETE request to the URI http://example.com/book/[Book ISBN]. The body of the request doesn't have to contain anything
• To add a new book, the clients makes an HTTP POST request to the URI http://example.com/book/. The body of the request contains the comments that the new book should have as well as the ISBN that should be assigned to it

Okay. So that was pretty simplistic and straightforward. We converted the URIs so that they are the same when referencing a single type of resource. It also changes to that when there is a resource that is to be addressed it is done so in the URI rather than using the request body. Lastly, instead of exposing new URIs for each action to be performed on a resource we take advantage of preexisting HTTP methods that meant to be used for this very same purpose.

Excellent idea. Sounds really great! But wait, what if you don't have a single resource that you're addressing each time? Does REST still work? For example, what if you have a service that allows a user to use a fat client in a bank to create new accounts for people. The database that stores all this information is a national database located miles away and there a web service that the fat client interacts with.

So here lies the problem. I imagine that an account can be a resource. That makes total sense. But what if the workflow is such that it splits the account creation into multiple pieces. First the user is required to enter their personal information, then their employment information, then information about their demographics or something like that. Each time you're using the service to address the same resource, the bank account, but passing different information. Sure you could create the resource at first and every subsequent interaction with the service you are simply updating the existing resource. It would work, but it doesn't really seem like the most elegant way to solve such a problem.

In fact, this problem would exist for all wizard-like forms that a user would use for both a service and/or a web page (after all, a web page is just a service but with a different response type: a html document). Consider a search service which lets you accumulate criteria using subsequent requests on the server and then search returning to the client all the results. That wouldn't work though because then we're not stateless anymore. The server has to know about the client and keep track of their accumulated criteria. How do you solve a problem such as this?

Anyway, I was just thinking off the top of my head. I have a feeling that this next chapter that I read will answer all my questions anyway or rather declare that you can't do something like that with RESTful services, you're better off using something stateful. But these are real-world problems that I've encountered before where a resource creation is done piecemeal and the client cannot retain all the information on its own. This forces the server to become stateful and there doesn't seem to be way around it.

If you know how to address a problem like that, feel free to let me know cause right now I can't think of anything.

In summary, the book is good. It didn't put me to sleep and it actually make me want to think about how I could change things that I've seen designed to be more RESTful.