RESTful web services

This is a copy of an email I just sent to a co-worker that I thought might be worth preserving.

"I’m looking for a really good RESTful webservices book...."

The three I have looked at are:

• RESTful Web Services Cookbook by Subbu Allamaraju, is probably the one I would recommend. It follows the O'Reilly "cookbook" format, which I hate, but it has more specific details that aren't found in blog posts and product documentation.
• RESTful Web Services by Leonard Richardson and Sam Ruby, is another one I would recommend. In fact, it is the more generic introduction to RESTy stuff, but since the devil is in the details, I kind of prefer the cookbook. On the other hand, if you're looking for two books, I would get both.
• RESTful Java with JAX-RS by Bill Burke, which is focused primarily on the Java JSR-311/JAX-RS framework.

The one important blog post I would like to mention is Roy Fielding's "REST APIs must be hypertext-driven". Fielding produces exceptional gibberish, but that post has the three (really, two and a half) points that most RESTful stuff misses:

1. "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources...or in defining ... hypertext-enabled mark-up for existing standard media types." The important part of REST, as a networking strategy in general, is the focus on the "document", the messages exchanged on the wire describing the "resources". Almost everything else is actually an implementation detail that should be pinned down later.
2. "A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations." Most of the REST documentation spends a lot of time on "URL paths", which is a complete waste of time since the client shouldn't care where the resources are.
3. "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience.... From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations...." This is a corollary of #2; every operation the client invokes should be driven from a URL received in a previous operation. The key point is that all the client needs to know is a single "touchpoint" URL and the format of the documents sent back and forth.

Here endeth the lesson.