BOTW: REST API Design Rulebook

This week I read the “REST API Design Rulebook” by Mark Massé. The concept of ‘representational state transfer’, i.e. REST, is hotly debated among programmers. My own professional experience in web development provided multiple perspectives about what is or is not ‘RESTful’, and I have to admit that I became quite fascinated by the concept and its perception and implementations in the software industry.

This post, however, is about Massé’s book. I am going to assume readers are familiar with REST to some degree. Those who aren’t should start with Roy Fielding’s dissertation, which is the origin of REST. I know a dissertation is not exactly the most fun and exciting read in the world, but there are a ton of articles about REST on the Internet with differing opinions so you can do no better than to start with the definitive origin and read additional material later (particularly the writings of Tim-Berners Lee, Leonard Richardson, and Sam Ruby).

Literally a Rulebook

The REST API Design Rulebook is exactly that: a list of rules grouped into chapters. Author Mark Massé begins with a brief introduction to the subject and closely related concepts such as HTTP, but the book silently assumes an amount of familiarity on the part of the reader. In particular, any reader should have programming experience with web applications, because without that the proposed rationale for many of the rules will likely not make sense.

The rules which the author proposes are both reasonable and controversial. Blunt rules such as ‘never return the HTTP status code 302’ are supported with sensible explanations and citations from authoritative sources. Other rules like ‘JSON should be supported for resource representation’ are apt to spark heated debate. There is an example of where the book’s rules embrace the trends of the majority instead of following any specific standard. The text readily admits that it favors JSON and XML because those are the most common formats that programmers use in conjunction with REST.

The result is a rulebook that attempts to make some common industry practices canonical. Personally I do not have an issue with this since Mark Massé clearly understands the REST landscape and current trends; much of what he proposes is encapsulating the tendencies of existing REST API design, related frameworks, et ceterIa. But I can easily imagine some developers taking issue with rules such as, “File extensions should not be included in URIs.” For example: GitHub should not support tacking .patch on to the end of URIs, something that I take advantage of in my workflow.

The author drew the line on certain design issues and not everyone will agree with them. In other words, this is not a completely objective rulebook we’re talking about.


References to WRML are spread throughout the book. This bothered me because there are already enough REST-related proposed standards and frameworks and data formats floating around the Internet. Introducing yet another felt like unnecessary baggage. Granted, WRML is interesting and has worthwhile merit. But its presentation in the book smacked of being personal promotion that felt out of place when content on the same page is also citing international standards like RFC 2616.

Still a Great Set of Rules

I realize I’ve written little about the content. That is because doing so would easily become a tutorial about REST. That said, at just over one-hundred pages the REST API Design Rulebook contains a fantastic set of rules and guidelines that I would personally recommend to all web developers. The explanations and examples are succinct but expressive. Massé’s book is dense with information and deserves multiple reads. Many of the rules within made me think, “Oh man I wish I had thought of that when doing….” Web developers owe it at least one read if only to see how deep the rabbit hole of REST goes.

Next Book of the Week

Next week I am reading “Mathematics for Computer Graphics” by John Vince. It feels like it’s been a while since I’ve read anything heavy on math, so it should be fun.


Add Your Thoughts

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s