Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Please, Don’t Call Them RESTful

DZone's Guide to

Please, Don’t Call Them RESTful

A lot of people tend to use the word RESTful incorrectly. Read on to get one dev's take on why REST is so misunderstood.

· Integration Zone ·
Free Resource

Are your API program basics covered? Read the 5 Pillars of Full Lifecycle API Management eBook

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.

Image title

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?

How to insult a developer

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.

Establish API creation, publishing and discovery as a master practice with the API Management Playbook.

Topics:
rest api ,restful api ,web api ,http api ,integration

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}