REST for Internet Arguments – RESTful Interface

This is an adaptation of a lightning talk I gave at PDX Ruby on November 3rd, 2015.

A while back, I was looking at the documentation for Mandrill’s API. I pulled the following quote from https://mandrillapp.com/api/docs/ on 11/05/2015:

The Mandrill API is a mostly RESTful API. Known caveats:

• All API calls should be made with HTTP POST.
• You can consider any non-200 HTTP response code an error – the returned data will contain more detailed information
• All methods are accessed via: https://mandrillapp.com/api/1.0/SOME-METHOD.OUTPUT_FORMAT

“THAT’S NOT EVEN CLOSE TO REST”, I screamed from the heavens (Twitter). “I KNOW WHAT A RESTFUL INTERFACE IS AND THAT’S NOT IT. I’M A PROFESSIONAL. GOSH. REST USES STATUS CODES AND HTTP VERBS MORE INTELLIGENTLY THAN THAT.”

That tweet was linked to my Facebook, and I got into an internet argument with a developer friend. I eventually lost that argument.

Here’s an outline of my understanding of what REST is, in a practical sense. It’s also the understanding of most Rails developers I know, especially juniors like myself.

• REST is a protocol.
• REST uses HTTP verbs and status codes (e.g. the server returns a 200 for a successful GET, a 204 for a successful DELETE, etc.)
• RESTful routes pluralize their resource names (e.g. /users/ instead of /user/)
• REST uses nested resource routes to access resources (e.g. /users/:user_id/photos/:id)
• REST is the thing that Rails enforces.
• This graph sums it up nicely.

This is a good working definition for when you’re discussing development, especially in a Rails environment. Unfortunately, it won’t win you arguments with pedants online. None of the above properties are specified by REST as originally designed.

SO WHAT IS REST

First of all, REST is an architectural style, not a protocol. There are many, many ways to meet its requirements.

Here are the constraints imposed on RESTful services, pulled from Wikipedia:

• Client server model
• Statelessness
• Cacheability
• Layered system (ie allow intermediary servers / proxies)
• Uniform interace
  • identify resources
  • manipulate resources
  • self-descriptive messages
  • Hypertext as the Engine of Application State (HATEOAS)

REST was developed by Roy Fielding, one of the principal architects of HTTP itself. You may notice that most of the constraints are fulfilled by HTTP. Further, there is no mention of how an API’s uniform interface should be structured, and whether it uses verbs and status codes “correctly”. In short:

Any API which uses HTTP is already “mostly RESTful”. Mandrill is correct when they describe themselves as such.

What’s HATEOAS?

The most interesting and most often-ignored constraint of REST as originally defined is HATEOAS. It implies discoverability. That is to say, from an entry-level API endpoint, you should be able to navigate to other any other endpoint via hypertext. In an API that perfectly implements HATEOAS, there is no need for documentation as such; you’d be able to navigate and explore it just as you would any other web service, like a website.

It turns out almost no one does this. The best example I know is Github. Here’s part of an example Github API response:

  "tree": {
    "url": "https://api.github.com/repos/octocat/Hello-World...",
    "sha": "691272480426f78a0138979dd3ce63b77f706feb"
  },
  "parents": [
    {
      "url": "https://api.github.com/repos/octocat/Hello-...",
      "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5"
    } 
...

The “url” key in each of these resources is HATEOAS. It’s really flipping cool. Almost no one bothers with this.

IN SHORT

By the most pedantic, fairly unpractical, definition of REST, almost every API is mostly RESTful. Very few are completely. Keep this in mind when arguing online.