A Measure

by Subbu Allamaraju on July 8, 2009

As we work through various aspects of designing and developing RESTful applications and documenting recipes in our RESTful Web Services Cookbook, we realized the need for a way to measure the quality of guidance that this book provides.

There are several ways to come up with a measure. We could use Roy’s definition of REST in its purest form as the measure. Or, we could rely on web standards such as HTTP, URI, Atom, AtomPub, HTML, XML, RDF etc, and advocate a standards-driven approach for RESTful applications. Alternatively we could look through the lens of software infrastructure such as web servers, proxies, caches, programming libraries etc. as well as ease of programming, and general principles of building distributed systems. Another possibility is to use a combination of all of the above, applied on a case by case basis.

Until recently, we were using the last approach – a combination of all of the above. But we could not put it to use consistently. It didn’t always help us decide between options. As we were mulling through different angles – going through multiple rounds of edits, writes, and rewrites, it became apparent that we needed a much simpler measure that can tell us quickly, and unambiguously, whether any given recipe is worth including in this book. Finally, we came up with this simple yardstick.

Can we, with a straight face, explain and justify any given recipe in this book to our prospective readers? If the answer is yes, the recipe stays. If not, it’s out.

Why did we settle on this non-technical yardstick? Because, of all the material out there on REST, there is a non-trivial amount of literature that neither of us can justify with a straight face in an informal setting. There are several recommendations that, on paper, look fine but in real-life, don’t make much sense. There are standards and practices that are technically correct, but cause more work or introduce headaches, and hurdles to success.

P.S. We still have nearly 30% of the first draft pending. Once we finish up the first draft, we plan to spend more time on this blog. Thanks for your feedback so far.

{ 1 comment… read it below or add one }

Josef Finsel July 8, 2009 at 3:14 pm

I have to say, that should be a marketing blurb on the book. To know the authors are going to use that as their measuring stick makes the book a lot more useful to work-a-day programmers like myself.

Look forward to reading it.


Leave a Comment

{ 1 trackback }

Previous post:

Next post: