REST API Design Rulebook By Mark Masse
Over the weekend, I read The REST API Design Rulebook by Mark Masse. I absolutely loved this book! In a world where so many computer science questions are answered with, "It depends," or, "there's no 'right' answer," Masse comes through with a book that says, No, these are the rules - this is how you design a RESTful API. This book explores all aspects of RESTful API design through an exhaustive set of concise, unambiguous rules that challenge you to think carefully and deeply about your choices.
| |
|
|
||
| |
 |
|
||
| |
|
|
While I absolutely love the way this book is presented, I don't necessarily see myself adopting all of the concepts Masse describes. For example, the use of WRML - his Web Resource Modeling Language - seems like a little too much effort to me, at least for the moment; I suspect that I can still get a tremendous amount of value from my RESTful APIs without having to add Schema and Format components to my HTTP headers.
But that's OK. As much as this book is about Rules, Masse fully understands that his rules may be challenged, or even rejected:
This book presents a set of REST API design rules that aim to provide clear and concise answers to the nagging questions listed above. The rules are here to help you design REST APIs with consistency that can be leveraged by the clients that use them. These rules can be followed as a complete set or a la carte. You may contest the rules, but I believe that each one warrants careful consideration. (Page 23 of 186)
After this disclaimer, Masse goes on to bring a level of clarity and consciousness to all aspects of RESTful API design. This includes, but is not limited to how your domains and sub-domains should be chosen; how your URIs (Universal Resource Identifiers) should be structured; what HTTP verbs (ex. PUT, POST, GET, DELETE) should be used for which types of resources and action; how to choose the correct HTTP Status Code response; how to define your response body (and when to exclude a response body); how to link to related content and actions (within your response); and, how to chose the correct Content-Type header values.
Take that last one, as an example - choosing the correct the Content-Type header value. When I return content in a request, I more or less use the content-types that I see other people using. In the past, when I've returned JSON content, I've gone with any one of the following:
- text/json
- application/json
- application/x-json
I don't actually know which one is right - I just copy others; but, as Masse explains, there doesn't have to be any guesswork involved. The Internet Assigned Numbers Authority (IANA) aggregates the standards for content type selection. For JSON, the standard is:
application/json
The book is so rule-driven that it's hard to talk about it without actually just repeating the rules that Masse has outlined. All I can really say is that I truly enjoyed this book. It has definitely made me question a lot of the choices that I've made in RESTful API design; and, it has me wanting to think more deeply and carefully about my choices going forward. I would say this book is a must-read for any server-side developers, especially those who are even thinking about taking on RESTful API deployment.
Reader Comments
I forgot to include a link to the Intenet Assigned Numbers Authority:
http://www.iana.org/assignments/media-types/index.html
It's seems pretty comprehensive. In the book Masse points out that most RESTful APIs will deal with content-types that fall under the primary category:
application/*
As far as I can tell, WRML is not a standard but just something the author came up with. Seems pretty convoluted to me.
Have you read RESTful Web Services Cookbook (http://shop.oreilly.com/product/9780596801694.do) seems like a more in-depth resource. I enjoyed reading it, and it seemed to me to have the same level of "this is what you're supposed to do".
@Jordan,
Yeah, WRML was created by Mark Masse (author of the book). I also found it to be a bit convoluted. I suppose it is intended to allow the Client to be able to programmaticaly respond to changes in the API (as opposed to versioning the API or hardcoding values in the client code)... but, it feels a little bit to me like an unnecessary step that will end up making the client code more complex than is necessary.
I haven't seen that Cookbook, I'll check it out! Thanks for the link!
Ben, thanks for recommending that book. I just bought and read it and I'm now basking in the warm glow of a few light bulb moments! LIke you, I don't think I'll be using WMRL, but the API "rules" are extremely helpful.