Most explanations of the REST architectural pattern out there are overly abstract and computer-sciency. They are very hard to digest to if you have little to no experience in web development.

Here's an illustrated tale to explain what RESTful architecture is like you were a 6 year-old who knows the internet kinda exists and it involves something called servers.

Asim, the pyramid architect

A very, very long time ago in Ancient Egypt, there was an architect. His name was Asim. Unlike other architects who built massive pyramids, Asim's job was slightly different. He specialized in building very small, unipersonal pyramids for the nobles of Luxor.

Asim received orders to build many small pyramids that needed to be finished promptly. All these pyramids looked almost the same, but Asim allowed his clients to choose the color. All pyramids also had a unique id number and a noble who would be placed inside once Anubis came knocking.

Asim was a hands-on architect that enjoyed being close to the building site. From the frontlines he could quickly oversee how many pyramids had been done so far and tell the builders exactly what he needed. If mistakes happened, Asim could react immediately and fix them before it was too late.

Building from the distance

Unfortunately, Asim was struck with a strange sickness that made him intolerant to high temperatures. Doctors recommended him to leave Luxor and move to Alexandria, where the weather was milder.

Despite his condition, Asim did not intend to retire anytime soon. He needed to find an effective way of managing the building site from Alexandria and keep delivering pyramids while he was away.

A couple days after settling in his new residence, Asim went back to work. , He sent very detailed instructions to the builders via the Egyptian mail.

He wrote the following:

Dear building team.

I would like you to complete the following request. 

Take noble Adom's pyramid and paint it black. Noble Kadesh apparently no longer
needs his pyramid and wants a new one in green, so we can destroy the current one
and get to work. 

Also, please refer to the notes of our last meeting
and create a blue pyramid for noble Maat. Once you are done, 
please send me a report with the latest state of all the pyramids. 

Unfortunately for Asim, this is the report that got back from the construction site.

Dear Asim,

After duly following your instructions, we are pleased to report 
the current state of the building site:

- Pyramid 1 - color: red, nobleman: Adom
- Pyramid 2 - color: green, nobleman: Maat - destroyed
- Pyramid 3 - color: black, nobleman: Kadesh
- Pyramid 4 - color: blur, nobleman: Kadesh - newly created

Mayhem! The building site workers got Asim's intent mixed up! This was bad news, mistakes like these were very expensive in the pyramid business.

Building with a new message protocol

Asim had to think about a better way of communicating his wishes to the builders. He understood that he needed to modify the pyramids from a distance, and once the request was sent, the work would get started and there's nothing he could do if things would go in the wrong direction.

To make sure everything worked well, he created a message protocol with the following properties.

• Whenever Asim requested something from the building team, he would write very clearly which action should be performed.

• The messages would be very very simple. A message could only contain one action at a time to make sure the construction site did not mess the instructions up.

• If he would like to know what's the state of the pyramids, he would write GET at the beginning of the message.

• If he needed to commission a new pyramid, he would start the message with the word POST. To change an attribute in an existing pyramid, he would use PATCH.

• If a pyramid would need to be demolished, Asim would write DELETE at the beginning of the message.

• To minimize confusion, there would be no context in a request. No reference to previous meetings, past work or other documentation. All the information needed to carry out the work would be in the message itself.

• The building team should always write back after receiving a letter with the results of their work. If they did not understand the instructions, they should write back immediately asking for clarification and not do any work at all.

Despite his health, Asim went back to Luxor for a week to teach his new messaging protocol to the building team. When he came back to Alexandria, he was excited and ready to get started. First, he wanted to get an overview of all the pyramids in the construction site. His first request looked like this.

GET pyramids

And he got back in response:

success

- Pyramid 1 -> please send GET pyramids/1 for more details
- Pyramid 2 -> please send GET pyramids/2 for more details
- Pyramid 3 -> please send GET pyramids/3 for more details
- Pyramid 4 -> please send GET pyramids/4 for more details

Excellent! The message protocol was working. After receiving this message, Asim enquired about the details of pyramid 3

GET pyramids/3

Gladly, Asim got the details he expected

success

pyramid 3
color: black
noble: Chasisi

He then requested a new pyramid for his good friend Baahir, a well-known scholar in Luxor.

POST pyramids

color: black
noble: Baahir

To the delight of his eyes, Asim got the following response

success

created pyramid 5
color: black
noble: Baahir

Asim also wanted to know if the builders were diligent when a message was not well written. To test them, he wrote an incomplete request:

POST pyramids

color: black

The building team spotted the error on the message and responded with:

error on new pyramid request

Original request:
 color: black

Please send a new POST request including both the **color** and the **nobleman**.

The protocol was working wonders! If he needed to change a pyramid, all he needed to do is a short PATCH message. For instance, if he wanted to change the color of the pyramid for his friend Rashida to red, it would be something like.

PATCH pyramid/4
color: red

or if he needed to demolish the first pyramid

DELETE pyramid/1 

Tying the Pyramids back to the Web

This little contrived tale you read aims to illustrate some of the key ideas behind REST in a palatable manner. Let's bring them back to the realm of software development.

REST is about clients and servers

The REST architectural style imposes a client-server constraint, so both parts of the system can communicate and evolve completely independently. In our tale, our unwavering architect acts as the client when he moved to Alexandria*.* The building team at the construction site represents the server.

In REST, clients and servers exchange information about resources

Our little story revolves around the idea of pyramids that are inspected, built, edited and destroyed. In REST parlance, the pyramids map to the idea of a resource. Resources are, broadly speaking, domain models or services that are exposed by an application. Some examples:

• In the Trello API, some of the resources are boards, lists, and cards.
• The Stripe API exposes resources such payments, refunds, subscriptions, orders and much more.
• Simple APIs like PokeAPI exposes all the pokemon ever as resources.

Client and Server communicate with requests and responses

Asim sent letters to the building site. On the web, clients send requests to servers over the http protocol. Technically, you could have a REST architecture without using http. It's just not very frequent.

As requests, the client uses:

• an HTTP verb, which declares what action will be done with the resource of operation to perform. Just like in the tale, http verbs also are GET, POST, PATCH and DELETE. There's a few more, in case you are interested.

• a header, which allows to pass additional metadata about the request. The messages in our tale did not cover headers to keep it simple.

• a unique path to a resource. In the tale, we had /pyramids, and /pyramids/:id . In the real world, you might find similar paths like https://api.trello.com/1/boards/:id

• an optional message body. Some requests might need additional information for the server to its job. In the story, Asim would add the details of a new pyramid whenever he POSTed to the building site, so the builders knew what needed to be done.

The workers in the building site always sent a letter back to Asim as a response. In REST, the server responds with a response when a request comes through. A response should contain:

• a status code, which flags what was the result of the operation on the server. In the story, we simplified these with success and error . The http protocol uses a bunch of numeric response codes that give you more detail on what happened, you can learn more about them here

• a response body, which contains data the client can use. In the world of REST APIs, this is usually JSON, but XML data or media files are also possible.

REST Resources should behave like hyperlinks on the web

In our story, Asim requested for all information about all his pyramids, and the response included information on how to get information for a specific pyramid, allowing him to send a follow-up request.

This is another crucial aspect of REST pattern. Just like a Wikipedia article links to other articles that are related, a response should contain all the information needed to dig deeper.

For instance, say you wanted my github profile information from api.github/users/libsyz. The response you get will look like this

{
  "login": "libsyz",
  "id": 22333041,
  "node_id": "MDQ6VXNlcjIyMzMzMDQx",
  "avatar_url": "https://avatars.githubusercontent.com/u/22333041?v=4",
  "gravatar_id": "",
  "url": "https://api.github.com/users/libsyz",
...

If you wanted to get the avatar image, you don't need to second-guess the path or look it up the docs, the response itself lets you know what is the path that you need to get it.

No context kept between requests

After coming up with the protocol, Asim's messages could be processed independently. They don't rely on previous knowledge by the building site, or information contained in a separate request.

If our architect hired a larger team of architects working remotely from Alexandria and opened several building sites in the future, the current message protocol would still be reliable.

This is possible because all the requests are stateless, and it's another key design characteristic in the REST pattern. Client context and knowledge cannot be stored on the server between requests. This property keeps client and server decoupled, making the whole system tidier and easier to manage.

This has deeper implications. The client does not even need to know who is the server, or if there are different servers taking care of different requests. The server does not need to what is being done with the responses and any implementation details on the client side.

This also helps with scalability on the server side ( imagine a bunch of services being ran by several servers, but all under the same API umbrella ) and the client side ( both a mobile app and a desktop can consume the same API but do different things with the data they consume.

This is just the beginning - go start building!

This pyramid story is an accessible yet incomplete analogy. My drawing skills are questionable to say the least. The explanations above are by no means exhaustive of what is REST and what it solves for. I have not covered other key concepts like cacheability, versioning or code on demand. Yet, I hope it gave you a better starting point to explore a design pattern that is crucial in web development and the modern API economy. I hope this post helped you if you were trying to make sense of what REST is and the problem it solves for, thanks so much for reading!