REST lessons learned by Mark Seemann
This post provides an overview of some lessons I learned while bulding non-trivial REST APIs.
Last year I spent a good deal of the year designing and implementing a handful of non-trivial REST APIs for a customer of mine. During that process, I learned some small lessons about the design of RESTful systems that I haven't seen described elsewhere, and I want to share these lessons with you.
In order to learn the concepts and philosphy behind REST, I think that REST in Practice is a great resource (pun intended), but when it comes to practical guidance, I find the RESTful Web Services Cookbook invaluable. It's full of useful and concrete tips and tricks for building RESTful APIs, but I don't remember reading about the following lessons, that I had to learn the hard way.
There's so much hype and misrepresentation about REST that I have to point out that when I'm talking about REST, I mean full-on, level 3 REST, with resources, verbs, hypermedia controls and the works.
Each of these lessons deserves a small article of its own, but here's an overview:
- Avoid user-supplied data in URI segments
- Avoid 204 responses
- Avoid hackable URLs
- Consider a home link on all resources
- Consider a self link on all resources
- Consider including identity in URLs
I hope you find these tips useful.
