The levels of REST

Imagine a web-based image hosting service. You can upload an image, and you can browse images by tags, and you can view image details. You are human (if you aren't, please stop reading this article!), you've probably seen something similar before, and you can use it pretty easily. Now, what if you weren't you but a computer program?

The World Wide Web

First, a refresher on the World Wide Web, aka the WWW, aka the web. The web was created by Sir Tim Berners-Lee before he became a Sir. In fact, him creating the WWW was the reason he became a Sir!

The WWW is using the internet and the HTTP protocol as its underlying infrastructure. The web is made of resources (web pages), which reside at URLs (such as https://tasuki.org/), and hyperlinks (such as this link to my personal homepage). It's pretty neat, humans like it a lot. Chances are, you're reading this very text through the web!

But what about computer programs?

So, you can use your browser to see web pages. Programs can do that, too. They can use the HTTP protocol to make calls to a remote server. Understanding the information on the web is certainly within their reach, but it might be more challenging for them — there's all this HTML and other hard to parse text. What if we wanted to make it easier for computer programs to use our image hosting service? We could create resources at URLs, following some structure and rules, so as to make it easier for computer programs to parse and understand.

HTTP refresher

... stands for HyperText Transfer Protocol. It's an application protocol the WWW runs on. Your yummy web pages are transported over this protocol.

HTTP defines methods the following methods:

• GET to retrieve information about a resource
• POST/PUT to create or update a resource
• DELETE to — you guessed it — delete a resource

There's a lot more to it. If you'd like to learn the basics, you can read the Mozilla overview of HTTP.

Enter REST

REST stands for Representational State Transfer. It's an architectural style that was created by Roy Fielding in 2000. Its purpose is making HTTP services more digestible for computer programs. Yummy.

REST has a lot of principles and rules, we'll cover some of them below.

Richardson Maturity Model

Remember when you were in school? You were getting graded on stuff. Well, now you can do the grading — of APIs that claim they adhere to REST. Leonard Richardson has created a ladder on which aspiring REST APIs can climb.

Level 0: Plain Old XML

Good news! If our API communicates over HTTP, it's already reached level 0. This is the level for which there are no rules. It's somewhat derisively called "plain old XML," but even using XML isn't actually a requirement. We're level 0 compliant!

Level 1: Resources

To be compliant with level 1, our API must be using resources that reside at their URLs. For our image hosting service, we might want to have the following URLs:

http://example.com/images                  # list of images
http://example.com/images/{image-id}       # specific image
http://example.com/tags                    # list of tags
http://example.com/tags/{tag-name}/images  # list of images with the tag

With this, we're level 1. Champagne!

Level 2: HTTP methods

We have to be level 1 compliant, and level 2 also requires us to use correct HTTP methods for operating on the resources.

GET  http://example.com/images    # retrieves a list of images
POST http://example.com/images    # uploads a new image, will return the image id

GET    http://example.com/images/{image-id}  # retrieves the specific image
PUT    http://example.com/images/{image-id}  # updates the specific image
DELETE http://example.com/images/{image-id}  # deletes the specific image

Level 3: HATEOAS

Hate-what? Hypermedia As The Engine Of Application State. It's a hipster way of saying that the response from the service includes hyperlinks to other resources.

Let's say we upload a new image POST http://example.com/images. The response should include the 201 Created HTTP status code header.

As I haven't mentioned status codes yet, and they aren't the focus of this post, you can learn more about HTTP status codes from Mozilla.

The contents of the response might look like:

{
  "name": "Unicorns",
  "tags": ["unicorn", "mythical", "horny"],
  "last_changed": "2018-05-05",
  "links": {
    "self": "http://example.com/images/42",
    "images": "http://example.com/images",
    "tags": "http://example.com/tags"
  }
}

We're using JSON here, but we could also use XML, CSV, or something else entirely. It's legal! Go wild!

We can see the response includes some data about the image we've uploaded, as well as useful links: to the uploaded image, but also to other related resources.

Let's say we want to view the existing tags with GET http://example.com/tags. We'll get a 200 OK HTTP status code and perhaps the following response:

{
  "tags": [
    {
      "tag": "unicorn",
      "number_of_images": 10,
      "links": {
        "self": "http://example.com/tags/unicorn",
        "images": "http://example.com/tags/unicorn/images"
      }
    }, {
      "tag": "mythical",
      "number_of_images": 2,
      "links": {
        "self": "http://example.com/tags/mythical",
        "images": "http://example.com/tags/mythical/images"
      }
    }, {
      "tag": "horny",
      "number_of_images": 100,
      "links": {
        "self": "http://example.com/tags/horny",
        "images": "http://example.com/tags/horny/images"
      }
    }
  ],
  "links": {
    "self": "http://example.com/tags",
    "images": "http://example.com/images"
  }
}

There! As a client to this service, we can just follow a link to view all the "mythical" images. We don't have to know about the URLs — we just need to know about the types of the available resources.

Now our service is level 3 on the Richardson Maturity Model scale, and we can pat ourselves on the back. This is REST!

Summary

REST standardizes how an HTTP API should be structured. It attempts to make it easier for computer programs to digest an API. The Richardson Maturity Model has the following levels:

1. Resources have their URLs
2. HTTP verbs (methods) are used for manipulating resources
3. Responses include links to other related/available resources

Further reading

Well we've just scratched the surface!

• HAL is a format for including hyperlinks in your responses. For simplicity and succinctness, we haven't used it here, but it's well worth to look into if you're working on a larger project.
• REST API tutorial is a longer and more thorough resource.