found drama

If you’re new to the world of REST APIs, and if you’re looking for a good set of working rules on how to design them, then Mark Massé’s REST API Design Rulebook (O’Reilly, 2012) should live up to its title just fine. It’s a short book (you could read it in an afternoon) and it tackles the subject matter in a direct and orderly fashion. It starts with a brief history lesson, quickly reviewing the history of the world wide web, of HTTP, and of the emergence of the whole notion of “RESTful” APIs and services. From there, he lays out the six constraints of the web’s architectural style, ¹ and how RESTful designs fit into that. The rest of the book is basically just a series of “rules” to follow when designing a REST API, along with use-cases, examples, and justifications for each of those rules. Many of these rules seem very common sense and sound a lot like every other bit of advice you’ve ever received about (for example) naming variables and methods; ² other rules seem sensible but get boxed in by “real-world” difficulties ³ or else seem counter to the prevailing wisdom; ⁴ still others seem to be little more than evangelizing for Massé’s own proposed WRML design/modeling framework.

For me, the highlight reel included: the first three chapters (on identifier design, interaction design, and metadata design), and some of the discussion in the final chapter (“Client Concerns”) about security, and the overview (however brief) of JSONP and CORS as solutions for some otherwise challenging situations.

The two bits where it went off the rails a bit for me: [1] Any of the discussion of “hypermedia” and/or between-document linking–I haven’t encountered this much (at all?) in the real-world and a lot of it seemed overkill to me, to go into that depth on how to link documents from within the API. ⁵ [2] WRML: what? Even after reading the whole book, I was still left wondering what exactly WRML was intended for, and what it would buy me as a developer. It seems that Massé wrote this book in part to evangelize this framework, but I could not quite get my mind sufficiently around it to say that I got it.

On the other hand, Massé does a great job with the “rules” (again: especially in the first half of the book) and I would recommend this to anyone that needs an introduction to REST API design. That being said, after absorbing this one, you’ll probably want to explore further with one of the other O’Reilly books on the subject, and/or find yourself a couple of resources on OAuth.

• Buy it on Amazon.com; or
• get the book directly from O’Reilly.

Disclosure: I received an electronic copy of this book from the publisher in exchange for writing this review.

1. [1] Client-server; [2] uniform interface; [3] layered system; [4] cache; [5] stateless; and [6] code-on-demand.[↩]
2. E.g., use singular nouns for documents; use plural nouns for collections and stores; use verbs (“and verb phrases”) for actions, etc.[↩]
3. In Chapter 2 (“Interaction Design with HTTP”) Massé advises you to use the pedantically correct HTTP methods for performing the corresponding actions: e.g., if you want to delete a document, send a DELETE request to the document’s URI. However, as most web developers already know, mainstream browsers will not respect any HTTP methods other than GET or POST–so you can forget trying to use PUT or DELETE as a form’s method, and you’re stuck using POST as a wrapper. (Here is a good Stack Overflow thread on the subject.)[↩]
4. E.g., all those API URIs that have a /v1/ in there somewhere? to specify the API version? Massé says: “Don’t do that.”[↩]
5. And as an aside, it was very unclear to me how the rel (relationship) attributes were even suposed to be defined. Some central standard? Part of WRML? Do you make stuff up and furnish an end-point in your RESTful API to explain the rels?[↩]

About Rob Friesel

3 Responses to review: REST API Design Rulebook