Tuesday 23 December 2014

Book review: REST Web APIs: The Book (win a copy here)

If you're a CFML user, you probably already know that one of the cornerstone members of the CFML community - Adam Tuttle - has recently written a book "REST Web APIs: The Book". I had the privilege of being one of the pre-release reviewers - from a content and language perspective - and Adam has now asked me if I could flesh out my perceptions a bit, as a book review. I've never been asked to do a book review before. Blimey.

OK, so we already know that Adam is the REST guru in the CFML world. He's the lead dev on the taffy.io project, the primary REST framework for both ColdFusion and Railo. It predates the vendors' own REST implementations, and is superior to them: it just has a better, more stable (in the case of ColdFusion), and more intuitive approach. This is a testament to Adam's knowledge on the subject of REST.

However this book is not about Taffy, nor is it CFML-centric. There is a chapter including some Taffy code examples, but this is the last chapter, and is just some "proof in the pudding" stuff. The book obviously needed some code examples. and CFML is an easily accessible language to provide said examples. Understanding the code does not get in the way of the topic being demonstrated.

What the book is about - and accomplishes very well - is the theory of REST. Adam makes a point of observing that whilst there's a wealth of information on REST out there, a lot of it is written from the approach of a very standards- or theory-oriented position, rather than with a real-world voice. Adam has solved this here. He's a developer, and he works with REST every day, he knows all the practical pitfalls, and also knows what he had to learn along the way to become a REST expert. Adam - who, full disclosure, is a personal friend - is also a very intelligent, witty and relaxed sort of fella, and this comes out in his writing. The book is very accessibly-written, and adds a touch of whimsy to what is a pretty dry topic (IMO anyhow. Not that it's different from a lot of technical-related topics).

The book covers the following topics:
  • Whats is REST, Anyway?
  • Some History, If You Want It
  • Close to the Metal
  • TL;DR: Don't Reinvent the Wheel
  • Security
  • Best Practices
  • Concrete Examples with Taffy
I've been aware of REST, and have thrown some examples together when testing ColdFusion's native implementation, but haven't really used it in anger. I had a bunch of questions: why does it do this? in this situation, what HTTP status code should I return? Should this be in the path in the URL or as a parameter? What is the difference between a POST and a PUT? And in reading the book I also had another question "HATEOAS? WTF?" All of these were carefully explained, and I really have learned a lot and feel comfortable that I actually get REST now. And it was an enjoyable read.

In the 70s when the Peter Benchley novel Jaws came out, the copy I had contained a quote from the Daily Express review:
Pick up Jaws before midnight, read the first five pages, and I guarantee you’ll be putting it down breathless and stunned, as dawn is breaking the next day
(I cannot source the original review, sorry)

And this was true of that novel. Not a word of a lie or exaggeration, I had a similar experience with REST Web APIs: The Book. I had to review it and decided to plug through the first chapter as I waited for my Tube ride home. I read a few pages, but did decide "actually... this is good stuff... I'll just read  a bit more...", and read it cover to cover in that one sitting. And that Jaws review did spring to mind as I did so.

It's a good book. Go grab it. URL again: "REST Web APIs: The Book". Go grab it if you already know about REST. Go grab it if you already use Taffy. If you're not familiar with CFML, don't see the mention of CFML as a barrier to entry: go grab the book. The bulk of the book is tech-agnostic, and as I say, CFML is very easy to read, so even the code examples will make sense. Go grab the book simply to support a fella in our community who's taken the time to write a book! How cool is that?

Or... Adam's authorised me to give a copy away, in some sort of competition. I've been racking my brains as to what the competition should involve, and not coming up with much. Like as I write this paragraph, I have no idea what this competition I am about to detail will be.

Um... I know. Lemme know what the biggest hurdle you've faced with REST has been, or something tricky that you took a while to "get". If you've not used REST before, let me know why. Just jot something down about something to do with REST, and the thing I find most interesting will get the book. That's a bit wishy-washy, I know, but so be it. I'm just wanting to give the book away really, and don't want to simply say "first come, first served".

Also as a rule of entry, pls retweet the Twitter status message referring to this review:

And, hey, Adam? Bloody well done mate. Good work.