Building APIs You Won’t Hate: Review

This is a review of Phil Sturgeon’s book Building APIs You Won’t Hate.

Building APIs You Won’t Hate

A bit of an edgy title, isn’t it? It makes sense, though. The potential of a developer hating anything he built given enough time to work on it is enormous. It’s an inverse parabola of sorts – your enthusiasm will grow for a given amount of time, and then proportionally drop until you sink below the starting point of pleasure. If you push through this depression, learn new techniques, and then apply them to your work you get a kind of sine wave in which your enthusiasm again rises until it starts dropping, and so on and so forth.

This book tries to help you make the climb along the parabola last as long as possible – its aim is to teach you some API development practices which make your APIs simpler, more robust, and more “people-who-are-not-you”-friendly.

Writing Style and Audience

Phil remains true to himself in a manuscript filled with humorous remarks, snarky comments, and practical examples. The chapters are well structured and fluidly presented with content breaks in just the right places, never making the book overwhelming or frustrating.

The audience of the book is, I would argue, intermediate and senior level developers who want to improve their existing design or just seek advice on how to get started with proper API development before they turn it into a mess they’re already expecting it to be. You will have little to no use of the book if you’re a junior, but maybe buying it and keeping it in your Leanpub shelf wouldn’t be a bad idea for when you’ve got a couple more notches on your PHP club.

The one downside is that Phil can’t spell to save his life. And not just typos and the occasional apostrophical butchery:

but also the cringeworthy grammar and at times milk-curdling phrasing. In typical Leanpub fashion, this is where the need for a professional editor really becomes obvious. Indie authors, I’m absolutely certain you know someone who studied English in at least some regard (and was relatively good) – ask them to read your work and correct it during writing, it’ll help loads. If you can’t find anyone, pay someone! Heck, I’ll do it for free, just send me your books.

This, though, is the only gripe I have with the book.

Technical Aspect and Content

Technically, this book excels on almost all levels.

The content is evergreen and bound to stay relevant for a while, with only the occasional reference to irrelevant operating systems and their package managers (OS X, Homebrew). These parts would have been better if replaced with a common Vagrant setup like Homestead or Homestead Improved in the book’s introduction, then demoing all further examples on it. Such an approach would have made the code parts more approachable to all readers, even keeping their URLs consistent, removing the need to mention home directories, example domains, etc. It’s a minor potential upgrade with a relatively minor positive reading flow effect, but still a potential upgrade.

As someone who deals with other people’s APIs daily and is working on his own, I could appreciate all the tips within. Not only does Phil go out of his way to recommend excellent accompanying tools to use during development and debugging (and show their basic use), his examples are all real-world and based on his experiences working on a heavy duty API.

Almost every chapter lists common approaches in designing a specific feature of an API and ends in a comparison of their pros and cons, usually culminating in the approach Phil took and preferred during his adventures. I found the authentication chapter particularly interesting, as that’s the only aspect of API development I’ve ever had problems with, though I would have preferred it to touch a bit more on the topic of ACL and role based control through the API request itself.

Having been published a while back, the book’s Documentation chapter is missing RAML as an option, but the chapter is so filled with practical instructions and step by step examples it doesn’t even matter – learning on a practical, real world example of documentation far outweighs the benefit of just hearing about a newer concept.

Content-wise, the only missing chapter is “Caching” and Phil acknowledges this in the book’s outro. Caching within the context of API development is an incredibly powerful topic, one I enjoyed hearing about in one of Ross Tuck’s talks at ZgPHP, and I do hope it’ll be added soon.

Conclusion

I’m giving the book a 4/5 with an elephpant killed off just because of the spelling and grammar and maybe a little bit because of the missing Cache chapter.

All in all, this book is a gold vein chock full of nuggets of valuable information and if you’re considering building an API for whatever purpose, give it a read. By the way, you can get it cheaper now – by using this link, the first 100 customers get a big discount.

Did you read it? What did you think?