Are your REST APIs really RESTful?

REST(REpresentational State Transfer) is an architectural style for distributed hypermedia systems. APIs that adhere to REST architecture are generally referred to as RESTful.
The motivation behind writing this article is that I myself misunderstood REST for a long time. Just using HTTP as a transfer protocol is not sufficient to classify a web API as RESTful(which is how I used to classify them initially :p). In fact, REST itself is independent of the transfer protocol. That said, this article assumes HTTP as the underlying transport protocol.

Photo by Kelly Sikkema on Unsplash

This article tries to explain the constraints that should be followed while designing an API to make it truly RESTful but I should mention that the developer should choose what they think is good for their use-case rather than being dogmatic about these constraints. Like if you control both client and server of your APIs then it might be more productive and quick to design RPC-styled APIs using some popular RPC implementations like gRPC. With that out of the way, let's dive into the REST APIs.

REST was first described by Roy Fielding in 2000 in his famous dissertation. REST aims to define a uniform connector interface between client and server by defining some constraints on their interaction. It defines interactions between client and server in terms of resources, client requests to fetch/update a resource(or collection of resources), the server returns a representation of the requested resource in simple formats like JSON and XML. HTTP verbs can be used to describe the operation that needs to be performed on the resource.
Following are different principles of REST architecture:

Client-Server

User interface concerns should be separated from the data storage concerns. The server holds the resource and the client sends a request to the server to manipulate this data. A REST system must function according to this client-server model.

Stateless

This is the most common and most widely known constraint of REST-style and probably you are already aware of this. It states that the server should not hold any context of the client between calls and each request from the client to server must contain all of the information necessary to understand the request.

Cache

Responses must define themselves as cacheable or not cacheable to potentially improve scalability. Here the focus is on HTTP caching rather than on server-side caching. Different things like ETag can be used for HTTP caching.

Layered System

In large-scale systems, clients are not directly connected to the end application server, there can be multiple layers like load balancers, other servers, etc. in between. Layered System constraint states that a client cannot know whether it is connected to the end server, or to an intermediate server. These layers should be completely hidden from the clients, to simplify the architecture.

Code On Demand (Optional)

This is an optional constraint that states the server can optionally send code to the client to execute/download locally (e.g., the server sending JavaScript code).

Uniform Interface

One of the central features of REST is its emphasis on the uniform interface. In REST style, any information exchange should take place in terms of resources. Any information provided by the server that can be named is a potential resource like a document, image, user, a collection of resources like posts, etc. Every resource is represented by a unique URI which can be used by the client to interact with the resource. A client also needs to have a representation of the resource which it can send to the server for updates. For example, assume a user resource with the following information available for the client:

Representation: {
 “userId”: integer
 “userName”: string
 “email”: string
 “passwordHash”: string
}

URI: http://server.com/user/{userId}: here userId should be sent by the client.
With this information, in order to update userName for a user with id 1, the client can first fetch that user using a GET call:

GET http://server.com/user/1

And then send received representation with new userName to the same endpoint using a PUT verb:

PUT http://server.com/user/1 (HTTP request body should have the updated representation of the user).

In REST, requests and responses must be self-descriptive, which means that the recipient receives all necessary information to understand the message and, for instance, must not wait for another message that explains how to interpret the data. By sending REST messages using standard means (e.g., correct HTTP verbs) to manipulate resources, the recipient of the message (server or client) receives all necessary information to complete its task.

Another important constraint for the uniform interface is HATEOAS (Hypermedia As The Engine Of Application State). This constraint states that server response messages must provide links to related resources. These resource links provide clients with other currently available actions, based on the client’s current state, which work as a navigation system throughout the API. e.g. assume an API endpoint for fetching accounts by ID:

Request: GET http://www.server.com/account/12345
Response body: {
  “account”: {
    “account_number”: 12345,
    “balance”: {
      “currency”: “usd”,
      “value”: 100.00
    },
    “links”: {
      “deposit”: “/accounts/12345/deposit”,
      “withdraw”: “/accounts/12345/withdraw”,
      “transfer”: “/accounts/12345/transfer”,
      “close”: “/accounts/12345/close”
    }
  }
}

In the above response, there are some links(like deposit, withdraw, etc.) that can be used by the client to perform different actions on the account without the need to have any prior knowledge of the structure of these links. This is primarily the essence of HATEOAS. The same APIs designed in RPC style will result in the following 5 different APIs:

getAccountById(…)
depositToAccount(…)
withdrawFromAccount(…)
transferToAccount(…)
closeAccount(…)

In this case, the client needs to know all the exposed endpoints and tightly couple to them in its code.

These are the six main principles of REST-style that I wanted to discuss. I hope this article was able to improve your understanding of RESTful APIs. I would love to know your opinion on these REST principles in the comments below.

Some Interesting Reads

• https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/
• https://cloud.google.com/blog/products/application-development/rest-vs-rpc-what-problems-are-you-trying-to-solve-with-your-apis
• https://www.researchgate.net/publication/325770704_An_Analysis_of_Public_REST_Web_Service_APIs — contains some good analysis of REST APIs and how compliant they are to REST principles.