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.