Menú Principal

Wednesday, May 30, 2012

My Review of REST API Design Rulebook

Originally submitted at O'Reilly
REST API Design Rulebook
Designing Consistent RESTful Web Service Interfaces

An Attempt to Unify the REST APIs
By Eder Andres Avila Niño from Paipa, Colombia on 5/30/2012
4out of 5
Pros: Easy to understand, Concise
Best Uses: Novice, Intermediate, Student
Describe Yourself: Developer
This a good book for beginners willing to understand what a REST API is about, its characteristics, HTTP methods and media resources in a short, concise, panoramic way. This book is an attempt to collect the best practices to expose the external behavior that a client, web or mobile, expects from a REST API server for processing requests and returning responses. For beginners, it offers a foundational knowledge about what a REST API should provide; and for experienced developers it offers an implicit 'audit' checklist to evaluate if their APIs are REST compliant.

For those software and web developers that want to enter to the REST API development, 'REST API Design Rulebook' is a good starting point since it explains through five sets of rules the underlying knowledge of a REST API, their structures, methods, documentation and suggested exposure to client applications and other APIs. On my opinion, and keeping proportions, this book, as a design pattern does, gives to developers the common vocabulary to discuss, specify, design, develop and test RESTful APIs.

The book's chapters are easy, quick reading, except chapter 5 'Representation Design' which is the one that requires more intellectual effort because it explains how to structure well-formed formats for message body (i.e. JSON), hypermedia (i.e. links), media schemas and API errors. Be careful with this chapter since it introduces a new Internet format not yet approved (the WRML), but on author's opinion this new format will become the client–server more verbose with respect to the format of a returned document (i.e. resource).

However, experienced REST developers may already know and have implemented many of the rules defined in the book, and instead be more interested in how to design the back-end service layers that conform to a RESTful API avoiding RPC or RMI practices, if possible. Such inner workings are not covered, but I think they could benefit from this book by performing a 'REST API compliant test' by taking this rulebook as a checklist.

By taking that implicit checklist approach, this book also has the side effect of providing several criteria to evaluate if a software framework that claims to help to the development of REST APIs indeed offers a full set of features that compliant with REST behavior, much more than routing HTTP requests and isolating from user interface artifacts.

Finally, in chapter 7 'Final Thoughts' the author depicts the need to unify a methodology to design a REST API that decreases disparities between APIs and improves team communication. Author depicts his solution known as the WRLM, akin to, say UML and RUP. On my opinion, a more detailed example included in this chapter would have been useful to show us the WRML's full potential rather than visiting the official web page.

In conclusion, 'REST API Design Rulebook' is a good starting point to understand how a REST API is composed, to acquire the proper vocabulary and to apply a more planned API design process. As a side effect, this rulebook helps to evaluate the RESTfulness of an existing API or developer framework.

Note: This review is in exchange for the O'Reilly Bloggers Review Program (

I review for the O'Reilly Blogger Review Program

1 comment:

  1. I have read this post. collection of post is a nice one ..that am doing website designing company chennai india and website development company chennai india. That I will inform about your post to my friends and all the best for your future posts..