REST - Representational State Transfer

Since the past 5 years, there has been an increasing demand to know how to build RESTful Web Services. Never had a job interview for Software Engineering failed to include at least one question about REST or RESTful Web Services and never a week passed with at least hearing one comment like “if we do x, it will not be RESTful”. Everyone seems to be on top of it, know everything about REST.
But is it true? Do they really know REST? How certain can one be that her system is RESTful?
Today I would like to share my point of view about REST by going through three points:

1. Overview
2. How does REST link with HTTP protocol
3. What have we learnt

1. Overview

Countless time, I have seen the following:

A: Do you know REST?
B: Yes
A: Can you write the URLs for a REST API for a user profile?
B: Ok, there;
    GET    /profiles
    GET    /profiles/123
    POST   /profiles
    PUT    /profiles/123
    PATCH  /profiles/123
    DELETE /profiles/123
A: Perfect

This probably looks familiar if you are a Software Engineer. The following conversation as well:

A: We need to design an endpoint which returns the profile
B: Ok let's do ~ GET /profiles(id:123,key:123)
A: Nah, that's not good.
B: Why?
A: This URL does not follow REST

Or another example:

A: We need to have an endpoint to start process X
B: Ok let's do POST /processes/X/start
A: Should we use POST or PUT?
B: If we follow REST, we will use PUT

I could go on and on. I am highly confident that you might have at least encountered one of those scenarios. Those discussions showcase fundamental flaws in the understanding of REST.

1. We reduced the definition of REST to the usage of HTTP methods for example POST vs PUT
2. We associated REST with the definition of URLs
3. We associated REST with HTTP

REST - representational state transfer, is not related to any HTTP verb nor is it tied to how URLs look like. In fact, REST is not related to HTTP.
REST is a set of guidelines which if followed will yield the benefits promise for a RESTful system. REST is not a protocol, not a standard, REST is a set of principles:

Client-server architecture
The client and server are decoupled. They follow a different lifecycle and can evolve independentely of each other.

Statelessness
Each request to the server is stateless. All information needed to perform the action at the server is provided by the client. In other words, all inputs are provided by the client for the server to perform its task.

Cacheability
Resources provided by your interface will provide their cacheability settings which will allow any server or client to know how to cache them.

Layered system
The client will not know the concrete server targeted. All access are abstracted by the interface (API). The client might be talking to a reverse proxy or to an authentication server or to your own server without knowing it, all being routed from a common interface.

Uniform interface
Resources can be accessed through URIs. There should be a common approach to access them and to act on them which is familiar with all other APIs. Each resource should have only one logical URI and when fetched, should return links which points to related resources.
The client should be able to discover the whole API content by navigating from the root (HATEOAS).

2. How does REST link with HTTP protocol

If REST is not related to HTTP, why is everyone linking them together and interchanging them?
Even if we look at the big players, Google, Airbnb, Uber, etc…, we can see how they too link both concepts together.

For example the following quote can be found in Uber API documentation:

The Uber API is a RESTful API. This means that the API is designed to allow you to get, create, update, delete objects with the HTTP verbs GET, POST, PUT, PATCH, DELETE.

The reason why REST is associated with HTTP protocol is that the HTTP protocol itself, if implemented in a certain way, answers part of the requirements of a RESTful service. Over the years it has become a default protocol to be used to build RESTful services and terminology has been mixed now speaking about RESTful APIs while speaking about HTTP web services respecting partially REST architecture.

The HTTP protocol is a well established protocol and extremely well documented. Implementing it allows;

1. client-server segregation by being the middle layer between client and server
2. it is inherently stateless
3. it contains all caching headers to allow clients to know how to cache resources
4. it abstracts away the physical location of the server
5. it provides HTTP methods which can be used to create a logical interface which can be similar in all other APIs

The only part which the HTTP protocol does not enforce is the implementation of a uniform interface and it is the origin of all the confusion. HTTP protocol does not dictate:

1. how someone would use GET or PATCH
2. how one should use the caching headers
3. what form should the response given back to the caller look alike

All this is what REST provides. It is a description of an architecture where HTTP can be used for the transport layer ~ because it’s convenient.

3. What have we learnt

If you ask me if my “APIs are RESTful”?
To be honest, it doesn’t matter.
The answer I will give you depend on which side you are in.

• If you are on the side which state that RESTful API should include HATEOAS, then my answer will be no. In fact it would mean that I have never built any RESTful system.
• If you are on the side which consider your service RESTful even though it does not implement all aspect of REST, then my answer will be maybe.

Why maybe? Simply because similarly, can I even call my system RESTful if I do not implement some aspects of the uniform interface, worse can I even call my system RESTful if it is partially represented as state transition?

Maybe the solution is to simply call our services Web APIs instead of RESTful APIs. If I had to take a side, I would take the I don’t care side.

Conclusion

Today is a big day, my 100th post! I wanted to take this opportunity to tackle REST and all its misconception. The message that I wanted to transmit is that there isn’t any right or wrong. There isn’t any side to choose. All that matters is how we master our own APIs.
How we provide to our users a unified way accross all our endpoints to understand and discover our APIs functionalities and best is if they can themselves guess what sort of functionalities we provide.
REST provides a handful set of guidelines which, if followed, yield nicely built APIs.
But so far, I have never built a truely 100% RESTful web service and I suspect most of us have not. Anyway all I am saying is that it doesn’t matter. Maybe one day I will realize that it does actually matter, until then, what matters to me is how comfortable are the users of my APIs. Hope you enjoyed this post as much as I enjoyed writting it! See you next time!