Please, Don’t Call Them RESTful

At the beginning of 2000, Douglas Crockford claimed that JavaScript was the World’s most misunderstood programming language. The reason for this misunderstanding was mainly due to bad naming, design errors, non-strict standard, etc. So, the misunderstanding was almost natural.

Last year I tweeted something similar about the REST architectural paradigm.

In fact, most people believe that to build a RESTful API you can simply create an API based on URLs and HTTP verbs. This is absolutely false.

This misunderstanding is going around for too long. But unlike JavaScript, the REST guidelines are clear enough. The name itself emphasizes the State Transfer, but this concept is the most ignored by the so-called RESTful API designers.

If you ask ten developers if their APIs support HATEOAS, at least nine will look at you with wide eyes saying: what f***ing are you talking about?

Yet the name speaks for itself. REST’s name says nothing about the protocols to be used and the way to identify a resource. It just speaks about REpresentational State Transfer. And state transfer management is a mandatory requirement for an API to be called RESTful, as Roy Fielding has stressed.

A true RESTful API is an API that provides the client with a new state and ways to switch to subsequent states. It provides a representation of a resource (not necessarily in JSON) and enriched links (hypermedia) to other related resources that may move the application to another state, as in the following example:

{
  "id": 463219,
  "firstName": "John",
  "lastName": "Smith",
  "company": "Acme Inc.",
  "salary": 72500,
  "links": [
    {
      "href": "https://api.myapp.com/employees/employee/463219",
      "rel": "self"
    },
    {
      "href": "https://api.myapp.com/companies/company/375",
      "rel": "company"
    },
    {
      "href": "https://api.myapp.com/payments/employee/463219",
      "rel": "payments"
    }
    ]
}

Here, the resource describes itself and provides information about related resources.

To be picky, it does not matter whether you use HTTP or another protocol. The key thing about the REST approach is that the server addresses the client state transitions. The state of the client is almost totally driven by the server and, for this reason, discussions on API versioning make little sense, too. All that a client should know about a RESTful interface should be the entry point. The rest should come from the interpretation of server responses. This is an interesting scenario rarely implemented.

APIs that simply map CRUD actions to HTTP verbs have nothing to do with Application State Transfer. You can call them Web APIs or HTTP APIs, but please don’t call them RESTful.