Wow, that’s a slap in the face of those incorrectly characterizing not RESTful APIs as RESTful! The year is 2008 and Roy Fielding is rightfully upset to see some authors of web applications incorrectly characterizing their applications as RESTful. He blogs about it in his blog post “REST APIs must be hypertext-driven”.
To answer Roy’s rhetorical question: No, I do not think that there is some broken manual somewhere that needs to be fixed 🙂
But in his groundbreaking dissertation about REST, Roy Fielding does not provide any counterexamples. I mean, he describes everything about REST, he leaves nothing out, he denotes its sharp contrast with RPC, he explains exactly how REST applications should be made and notes REST’s benefits and shortcomings. But counterexamples are also needed, like architectural decisions that are not RESTful, HTTP responses that are not RESTful and anything else that can show where things can go wrong.
When Roy Fielding wrote his dissertation, it is understandable that he did not expect such wide misuse of the REST architectural style. But now that he has observed it, he could provide us with counterexamples. He should not only just restate the REST principles, but also show examples of their incorrect use and how one could go on about restoring “RESTfulness”.
Since the REST architectural style is young, many implementations of it would be incorrect. The young and the RESTful. Oh, well…
I have just read Kelly Sommer’s excellent blog post “Clarifying REST“, which does exactly what I described here. An example that is not RESTful is provided and then a modification that makes it RESTful is presented. Sheer brilliance. Not only that, Kelly Sommers also provides an insightful analysis about the REST architecture and the REST constraints, i.e. its characteristics. But the thing that impressed me most is the post’s fairness and balance. Kelly Sommers points out that REST is one of the available architectural models and you do not have to abide to it, if you feel that another approach will be better in your case. It is when you declare that your application is RESTful that you have to follow all the REST rules.
Although REST concepts deserve a lot of discussion in order for someone to grasp them and also realize when she steers away from them, here is a rule of thumb that I picked up from Roy Fielding’s blog post: Apart from the knowledge of the initial URI to connect to, the client should have no other knowledge of the application. The client should be able to achieve everything it is supposed to just by relying on the URIs that are provided by the HTTP responses of the server.
Read my lips: no cookies. And another thing that is equally important: the server should have or retain no knowledge of state.
In magic, it is all done with strings and mirrors. In REST, it is all done with URIs.