« Troubleshooting Azure DNS Timeouts

REST Level 0.5

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?
— RivieraKid

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:

Level 0

  • Uses HTTP, but only as a transport mechanism.
  • All requests POST to one URL.
  • Plain old XML or JSON.

Level 1

  • Nouns (resources) instead of verbs (procedures).
  • Each resource gets its own URL, which includes the ID of the resource in the path.
  • The verb still goes in the request body or headers.

Level 2

  • Use HTTP verbs.
  • Use HTTP status codes.
  • Use GET to read resource(s).
  • Use POST to modify resource(s).
  • Better yet, use POST to create, PUT or PATCH to edit, and DELETE to, you know, delete.

Level 3

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.

The Problem

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.

Level 0.5

  • One URL per method.
  • Only use POST.
  • Only use these three status codes: 200, 400, and 500 for API method implementations.
  • Use standard HTTP headers and status codes for cross-cutting concerns like authentication, authorization, rate limiting, etc.
  • We like to use a standard JSON payload request with a JSON payload response.

A sample URL might look like this:

POST https://libraryresourcesapi.faithlife.com/v1/getTextRangesForWordNumbers

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