Understanding REST APIs through a Metaphor

Sudhir Chauhan

What is a REST API?

REST - Representational State Transfer is a software architectural style that was created to describe the design and guide the development of the architecture for the World Wide Web.
- It is an architectural style for designing networked applications.
- It uses HTTP methods to perform CRUD operations (Create, Retrieve, Update, Delete).
- Data is commonly exchanged in JSON or XML formats.

The Metaphor

Let's understand it through a metaphor. Imagine you own an automated clothes store with shelves of clothes, especially shirts. At the entrance, there’s a Robot that listens to your commands in a special language called REST. Let's conveniently call it Robo. To make the scenario more realistic, imagine that this robot doesn’t act on its own but delegates tasks to smaller, specialized robots called API Endpoint Functions.

The Robo will follow your instructions as long as they are valid. In the world of REST, these instructions are given using HTTP methods, which act like action words or verbs in a sentence.

Now, as dealing with HTTP Verbs is not very convenient, they are exposed to you through a website in a Web Browser.

[!NOTE]
When a link is clicked, a form is submitted, or a button is clicked, the browser translates it into an HTTP Verb and sends it to Robo.

Interacting with our REST Robo

In this section, we will explore how REST APIs work by simulating interactions with our REST Robo. Each interaction demonstrates a specific HTTP method and its corresponding operation on the store's inventory. These examples will help you understand how REST APIs handle requests and responses in a structured and predictable manner.

Interaction 1: Listing All Shirts with GET

To decide what to update, I should first know what I have in the store. I want to know how many shirts are in the store. To do this, I need to tell it to get all the shirts. For this, I click on "list all shirts." The browser translates the click into a GET Verb and sends it to Robo.

Browser: Hey Robo, give me all the shirts. 

GET /shirts

Robo: Wait here for a moment, please, while I see what I can do.

Robo searches through its list of API Endpoint Functions and finds a match in the get_shirts API Endpoint. It assigns the task and waits for a response.
When the response is ready:

Robo: Here are all the shirts you asked for. 

STATUS: 200 OK

{"shirts": [
  "shirt 1",
  "shirt 2",
  ...]}

The browser converts the list into the UI and displays it.

In case no match was found, it would have returned an error code:

STATUS: 404 NOT FOUND

This completes our first interaction.

Interaction 2: Getting Details of a Single Shirt with GET/shirt_id

Now that I have all the shirts, I can decide which one to replace. I notice the blue shirt with the old design. I want to know more details about it. I click on it.

Browser: Hey Robo, get me the third shirt from the list. 

GET /shirt/3

Robo: Happy to help; please wait a moment.

This time, Robo matches the request to the get_shirt API Endpoint, which needs to know the shirt number to fetch the details. It goes out, gets all the details of shirt number 3, and hands them back to Robo.

Robo: Here are all the details for shirt 3 that you asked for. 

STATUS: 200 OK

{"id": 3,
 "color": "blue",
 "size": "XXL"}

The browser takes the details and displays them.

But suppose get_shirt encountered an error and didn't get the details, then Robo would have returned:

STATUS: 404 NOT FOUND

This completes our second interaction.

Interaction 3: Creating a New Shirt with POST

Browser: Hey Robo, I got a new shirt; add it to your inventory. 

POST /shirts
{
  "color": "red",
  "size": "M"
}

Robo: Let me add that new shirt for you. Please wait a moment...
Robo: New shirt added successfully. 

STATUS: 201 Created

{"id": 5, "color": "red", "size": "M"}

The browser displays the new shirt in the inventory.

Interaction 4: Replace an Existing Shirt with PUT

Browser: Hey Robo, replace the fourth shirt with this new one. 

PUT /shirts/4
{
  "color": "yellow",
  "size": "L"
}

Robo: Replacing the fourth shirt. Please wait a moment...
Robo: Shirt replaced successfully. 

STATUS: 200 OK

{"id": 4, "color": "yellow", "size": "L"}

The browser shows the updated shirt.

Interaction 5: Updating a Shirt's Attribute with PATCH

Browser: Hey Robo, update the size of shirt 2 to XL. 

PATCH /shirts/2
{
  "size": "XL"
}

Robo: Updating shirt 2 with the new size. Please hold on...
Robo: Shirt updated successfully. 

STATUS: 200 OK

{"id": 2, "color": "blue", "size": "XL"}

The browser displays the updated details for shirt 2.

Interaction 6: Removing a Shirt with DELETE

Browser: Hey Robo, this shirt is out of fashion. Remove shirt 3. 

DELETE /shirts/3

Robo: Removing shirt 3. Please wait...
Robo: Shirt removed successfully. 

STATUS: 200 OK

The browser shows that shirt 3 has been removed from the inventory.

Core Concepts

REST APIs are built on a few fundamental concepts. Let's summarize them here to reinforce what we've learned:

Resources
  • Everything in REST is a resource (e.g., shirts, Posts, Products)
  • Each resource is identified by a unique URL
HTTP Methods

As we saw already, HTTP methods allow us to interact with REST API endpoints. Let's summarize them in one place now.

Method Endpoint Description
GET /shirts Retrieve all shirts
GET /shirts/{id} Retrieve shirt by ID
POST /shirts Create a new shirt
PUT /shirts/{id} Update entire shirt info
PATCH /shirts/{id} Modify part of shirt info
DELETE /shirts/{id} Delete a shirt

What Happens When You Ask?

If the robot understands, it will tell you:
- 200 OK - Request was successful
- 201 Created - Resource was successfully created
- 204 No Content - Update was successful, but no data is returned
- 400 Bad Request - Client sent an invalid request
- 401 Unauthorized - Authentication required
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource not found
- 500 Internal Server Error - Server encountered an error

REST API Best Practices

  • Use meaningful resource names (e.g., /shirts instead of /getshirts)
  • Follow a consistent URL structure
  • Use appropriate HTTP methods
  • Implement authentication & authorization (e.g., JWT, OAuth)
  • Support pagination & filtering for large datasets
  • Return useful error messages with proper status codes

Conclusion

Through the metaphor of the automated clothes store and the REST Robo, we have explored how REST APIs function in a real-world scenario. Each interaction demonstrated the use of HTTP methods to perform specific operations, such as retrieving, creating, updating, or deleting resources. By understanding these interactions, you can better appreciate the simplicity and power of REST APIs in building scalable and efficient web applications. Remember, the key to mastering REST lies in understanding its core principles and adhering to best practices.