RESTful Vs REST API Or Where Did REST Come From?

Once upon a time in 2000, Roy Fielding decided to describe how services can use HTTP for inter-service communication, this was a topic of his Ph.D. dissertation. The main idea was that HTTP at that time was a commonly used communication protocol and there was enough support in almost all languages as well as in infrastructure and tools. On the other hand, at that time SOAP existed, which was pretty complicated.

Roy Fielding: “REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, the generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems.”

Then in 2008, Leonard Richardson developed a model that breaks down the principal elements of a REST approach into three steps, it's called the "Richardson Maturity Model". These introduce resources, HTTP verbs, and hypermedia controls.

Here is a picture from Martin Fowler's description of the Richardson Maturity Model.

RESTful Vs REST API Or Where REST Came From?


A brief description of levels would be,

  • Level 0 is when all requests go to only one endpoint and use only one HTTP method (similar to GraphQL)
  • Level 1 is when different resources have their own endpoints, but uses the same HTTP method (close to RPC)
  • Level 2 is when the system uses the whole power of HTTP like methods, response statuses, headers, and query parameters (common for CRUD APIs nowadays)
  • Level 3 is Level 2 + HATEOAS (Hypertext As The Engine Of Application State)

HATEOAS

Basically, HATEOAS adds to the response model links to actions that may be performed from the current state of the resource, it reminds me of a state machine. The purpose is to make a self-descriptive REST API that may be explored without documents by the links provided. That is how server logic may be exposed to the client-side, similar to user interacts with the browser page.

Nowadays HATEOAS is rarely used due to complexity and lack of standardization for the format of its specification, so prior to implementing Level 3 teams should design the HATEOAS specification for their own services.

An approach that is comfortable for communication between people and websites is not suitable for machine communication due to the overhead of implementation and support on both sides of communication, especially when shared services are involved. That is why REST did not survive in its classic meaning and RESTful appeared.

So, REST(REpresentational State Transfer) is a classic "architectural style" from 2000 by Roy Fielding.

RESTful took simple and straightforward features from the Level 2 maturity model by Leonard Richardson of the classic REST by Roy Fielding.

Nowadays RESTful is typically used as an adjective describing web services implementing a REST architecture, which is usually understood differently from classic REST and close to the Level 2 maturity model stated above.

Hope you enjoy this historical topic.

You may like to read this article next,

Here are some books regarding this topic,