From time to time people ask me questions about RESTful architecture. I thought it might be helpful to list the resources that I keep near at hand for asnwering tricky REST questions.
- RFC2616 Hypertext Transfer Protocol: If you haven’t read this RFC, you might be surprised at what you don’t know about HTTP. I keep a printed copy nearby at all times.
- RFC5988: Web Linking. You might not have heard of this one, but I think it’s one of the more important recent developments in HTTP from a RESTful standpoint. REST is all about hyperlinks, but how do you link a non-HTML resource – like an image, for instance – to other resources? This RFC tells you how.
- URI Templates. This one’s still a draft. In general forcing clients to build their own URIs is bad form; contrary to a zillion “How to use our RESTful API” articles you may have read, URIs are supposed to be opaque. However, sometimes URI construction is inevitable; when that’s the case, we can at least specify it in a machine-understandable format with URI templates.
- HTTP: The Definitive Guide. A good HTTP reference is essential, and this book offers a lot more exposition and examples than plain RFC2616. It also draws in related material so you don’t have to go hunting down all the referenced RFCs yourself.
- Restful Web Services. Probably the best guide available for building REST services.
- RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity. The companion volume to RESTful Web Services.
- REST in Practice: Hypermedia and Systems Architecture – I haven’t delved deeply into this one yet, but it seems to deal with higher-level patterns built on the principles laid out in the other books.
- Roy Fielding’s thesis. Duh.
- The Richardson Maturity Model. Characterizing different levels of RESTfullness.
- Versioning REST Web Services, by Peter Williams. In which we learn a much better alternative to API endpoints with /v1/ and /v2/ in the URL.
- Versioning REST Services, by Scott Seely. An interesting variation on the scheme above that uses mimetype version arguments instead of a version built-in to the mimetype.
- Your Web Service Might Not be RESTful if… by Paul Sadauskas. Think you know REST? Think again.
- Haters gonna HATEOAS, by Magnus Holm and Steve Klabnik. One of the better explanations of just what the hell Hypertext As The Engine Of Application State (HATEOAS) means.
- Why HATEOAS, by Craig McLanahan. OK, so now you know your API isn’t really RESTful. Why should you care? This article provides a few reasons.
What about you? What are your favorite resources on RESTful architecture?
Note: Any comments to the tune of “blah blah REST orthodoxy blah blah zealots blah blah real world blah blah who cares” will be summarily deleted. The books and articles listed above are by real developers who have solved real deficiencies in HTTP APIs using RESTful principles. If you and/or your users don’t have the problems these techniques address, that’s fine. This article isn’t for you. Move along.