Book Review: REST API Design Rulebook
The Integration Zone is brought to you in partnership with Red Hat. Download the IDC Report: The Business Value of Red Hat Integration Products to learn more about Red hat Integration.
Book Review: REST API Design Rulebook (Mark Masse)
- The obvious shortcomings of SOAP style strong contracts
- They are a nice alternative to ESB's for integrating heterogeneous architectures
In 2010, Martin Fowler - in his excellent blog - discussed the Richardson Maturity Model. This model provided a very good categorisation technique to assess the degree of RESTfullness based on how many core REST principles were being used. Although, that same model gets a reference in Mark Masse's REST API Design Rulebook, Masse's book goes much more into low level detail about various REST best practises.
- Negative caching: adding cache headers not just for positive responses but to 3xx and 4xx responses. This is something that may not be obvious, but could be a good performance / scalability boost depending on the nature of your application and user usage patterns etc.
- How to version your URIs, your representational forms and your resource objects
- Using a consistent forms to represent link relations
- Don't end URI's with a slash
- Don't use underscores in URI paths
- Put "api" in the domain part of your rest resource path, e.g.
https://api.dropbox.com/1/oauth/request_tokenThe main reason why I think it is good to have a book like this is because when a development team are trying to use a REST style architecture, disagreements, misunderstanding will inevitably happen. For example, the proverbial: 'Should a URI end in a plural or singular noun?'
It is always good to be able to reference a respected industry resource to prevent rabbit holes appearing and eating into your valuable project time.
- Adding an ETag HTTP header to that shopping cart resource as items go in and out of it.
- Using query fields to generate partial responses and using the ! for an excludes option.
I do think this book is written more as if you were designing a public facing API. If you find yourself in that situation you should definitely, definitely, definitely be considering everything Massé is saying in the book. But note, the emphasis is on considering which doesn't always mean adhering or adopting.
The book does a very good job in covering best practises that a lot of developers just wouldn't think of (setting response headers such as content-length, setting the location header in responses for newly created resources, how to support HTTP 1.0 when you are trying to discourage caching) and is definitely worth a read but you really have to think about what makes sense for your project. As stated, some of the suggestions are quick wins others you have to assess the cost and the benefit. Following the core basic REST principles (statelessness, a good resource model, uniform interface etc.) is what is really important after that the challenge is figuring out what works best for each specific project and how to make the most of your time. That will vary from project to project and will depend on project scope, scale etc. A good architectural decision should always consider the various options but make the appropriate decision for the appropriate project.