RESTful web services

Posted on January 25, 2013 by Tommy McGuire
Labels: protocols, REST, books

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:

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.

active directory applied formal logic ashurbanipal authentication books c c++ comics conference continuations coq data structure digital humanities Dijkstra eclipse virgo electronics emacs goodreads haskell http java job Knuth ldap link linux lisp math naming nimrod notation OpenAM osgi parsing pony programming language protocols python quote quotes R random REST ruby rust SAML scala scheme shell software development system administration theory tip toy problems unix vmware yeti
Member of The Internet Defense League
Site proudly generated by Hakyll.