PHP
Article

Building APIs You Won’t Hate: Review

By Bruno Skvorc

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?

Free Guide:

7 Habits of Successful CTOs

"What makes a great CTO?" Engineering skills? Business savvy? An innate tendency to channel a mythical creature (ahem, unicorn)? All of the above? Discover the top traits of the most successful CTOs in this free guide.

Comments
peternijssen

Very good book indeed. I used it a lot as a reference for building our API.

gregrobson

apOStrophical (as in apOStrophe) not apSOtrophical.

If you're going to criticise somebody else's spelling, you should at least double check your own! If the spell checker doesn't pick it up, you should eyeball it!

philsturgeon

Thank you Bruno!

You've given me some great feedback. I've fixed those pro's and con's and a few other bits. I have had multiple technical editors go through this stuff, but certainly need to get a proper editor on the case. I'm doing that now.

Last year I was too busy being internationally homeless and broke to concern myself with such things, but now I'm back to work and stable I can certainly part with a little cash to get this book to the best quality it can be.

Thanks again!

swader

Doh! Thanks, fixed.

You're welcome - thanks for a great book.

I'd recommend opening a public repo for typo submissions and other issues like Brandon Savage did for his book. I spammed that repo with some 20 issues while I was reading, it was simple to have it open in another screen and just put the encountered errors there. In most cases, people won't bother to tell you about a mistake because it's minor (who really cares about "pro's" vs "pros"? - we all know what is meant by it), doesn't reduce the content's value, and - perhaps most importantly - because it's tedious to break the reading flow just to report a typo or make a note of where it was. People like me don't mind, we're trained to break flow to shoot lightning, but others may mind. Having an easy to access repo might take care of that last point for them. This would also make it easier to have multiple pairs of eyes go through it, rather than just hiring a solo editor, though doing both is probably the optimal approach.

Recommended
Sponsors
Because We Like You
Free Ebooks!

Grab SitePoint's top 10 web dev and design ebooks, completely free!

Get the latest in PHP, once a week, for free.