Book Review: The REST API Design Handbook

I’ve read a handful of books about REST, API design, and RESTful API design, but I’ve honestly never read a great book that effectively balanced the theory and practice. That changed when I finished reading enstratus CTO George Reese’s new ebook, The REST API Design Handbook.

I liked this book. A lot. Not quite a whitepaper, not exactly a full-length book, this eBook from Reese is a succinct look at the factors that go into RESTful API design. Reese’s deep background in this space lent instant credibility to this work and he freely admits his successes and failures in his pursuit to build a useful API for his customers.

I found the book to be quite practical. Reese isn’t a religious fanatic about one technology or the other and openly claims that SOAP is the fastest technology for building distributed applications and that XML can often be a valid choice for a situation (e.g. streaming data). However, Reese correctly points out that one of the main problems with SOAP is its hidden complexity and he frames the REST vs. SOAP  argument as one of “simplicity vs. complexity.” He spent just enough time on the “why REST?” question to influence my own thinking on the reasons that REST makes good sense for APIs.

That said, Reese points out the various places where a RESTful API can go horribly wrong. He highlighted cases of not applying the uniform interface (and just doing HTTP+XML and calling it REST), unnecessarily coupling the API resource model to the underlying implementation (e.g. using objects that are direct instantiations of database tables), and doing ineffective or inefficient authentication. Reese says that authentication is the hardest thing to do in a RESTful API, and he spends considerable time evaluating the options and conveying his preferences.

Reese deviated a bit when discussing API polling which he calls “the most common legitimate (but generally pointless) use of an API.” Here he goes into the steps necessary to build an (asynchronous) event notification system that reduces the need for wasteful polling. This topic didn’t directly address RESTful API design, but I appreciated this brief discussion as it is an oft-neglected part of management APIs.

Overall, to do RESTful APIs right, Reese reiterates the importance of sticking to the uniform interface, not creating your own failure codes, not ever deprecating and breaking client code (regardless of the messiness that this results in), and building a foundation that will cleanly scale in a straightforward way. I really enjoyed the practical tips that were strewn about the book and will definitely use the various design checklists when I’m working on interfaces for Tier 3.

Definitely consider picking up this affordable ebook that will likely impact how you build your next service API.

Author: Richard Seroter

Richard Seroter is Director of Developer Relations and Outbound Product Management at Google Cloud. He’s also an instructor at Pluralsight, a frequent public speaker, the author of multiple books on software design and development, and a former editor plus former 12-time Microsoft MVP for cloud. As Director of Developer Relations and Outbound Product Management, Richard leads an organization of Google Cloud developer advocates, engineers, platform builders, and outbound product managers that help customers find success in their cloud journey. Richard maintains a regularly updated blog on topics of architecture and solution design and can be found on Twitter as @rseroter.

Leave a Reply

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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.