I’ve read several articles about REST, even a bit of the original paper. But I still have quite a vague idea about what it is. I’m beginning to think that nobody knows, that it’s simply a very poorly defined concept. Like Web 2.0, everyone talked about it but nobody could give a clear definition. Thoughts?
This article will briefly lay out the Richardson Maturity Model of REST, which describes where an API sits in terms of RESTfulness. We’ll then propose a well-defined and simplified version of REST, called REST Level 0.5, which can be summarized on the back of a napkin. For brevity, we will not go into a deep discussion of REST or its history. For those interested in the history of REST and what it is, this is a great resource.
A summarized version of the Richardson Maturity Model includes:
POSTto one URL.
HATEOAS (Hypermedia As The Engine of Application State). Most APIs rarely venture this far. Essentially, requests can now return references to other resources as hyperlinks. This is outside the scope of our article, and unuseful for many APIs.
Many APIs will fall somewhere between level 0 and level 2, perhaps using a mixture of different levels for different parts.
The issue is level 2 is an awkward fit for many domains. There is a
DELETE, but not an
UNDELETE. Batching was explicitly not supported in the original REST paper, so various APIs roll their own implementations.
GET does not make sense for many authenticated APIs, where built-in caching is unwanted. Interactions between many different types of resources are not well defined. Many have their own interpretations and definitions of what REST even entails.
Thus, we propose REST Level 0.5, which takes the parts we found useful and provides a single, well-defined set of rules that is quickly learned. There are no silver bullets, but REST Level 0.5 has been found to work well on multiple APIs we’ve built. As always, there may be a better fit for your domain.
500for API method implementations.
JSONpayload request with a
A sample URL might look like this:
That’s it! Everything you need and nothing more.
For a detailed analysis, which includes many of the drawbacks of REST Level 0.5, we recorded a talk.
Posted by Erik Lanning on September 15, 2023