APIs à la Carte: Understanding API Requests Through a Restaurant Analogy

Understanding APIs:

Before we can even plan testing we need to know what are APIs and what they are used for. Simply said APIs allow different parts of the software system to communicate with each other.

Imagine software application is a restaurant. You enter a restaurant, sit by the table, waiter brings you the menu and you tell the waiter what meal you are ordering to eat. Waiter goes with this request to a restaurant chef and initiates order. Once a meal is ready, waiter brings it to you and order is completed. This is how software applications work. Let me explain you more in detail, but from a restaurant perspective.

Roles defined:
Restaurant role: Software application role

Restaurant: Entire software application
Restaurant Customer: Software application user
Kitchen: Server
Chef: Backend System
Waiter: API

There are several API requests that user can make in software application:

• GET
• POST
• PUT
• PATCH
• DELETE

Short explanation about what each request does:

GET:
Retrieves data from a server. You don't change anything, you just request to view available data from a certain endpoint.

POST:
Send data to the server. With it, we are sending new information to the server. In so called _body_ we send all the data.

PUT:
This method is commonly used to update an entire resource. You are essentially saying to the system: "Hey here is the entire new version of this resource, make an update."
Important to note is when making a PUT request we must provide entire resource data in the _body_

PATCH:
This method is also as PUT used for making updates, but this time we only provide those fields in the _body_ that we want to change. This makes PATCH more efficient than PUT.

DELETE:
As the name describes, it is used to request the server to remove the resource. Important to note is that this request is irreversible. Once a resource is deleted it cannot be recovered via HTTP protocol.

Explained GET request:

In restaurant world, a restaurant customer makes a GET request when he/she opens the menu and reads a list of meals, drinks and desserts. Another example would be, customer asking waiter: "Can I see the best red wine you have?" This is like a GET request. You are not ordering yet, you are just asking to see what's available. The waiter goes to kitchen (kitchen is like the server in software application) and brings you best red wine that they have, for you to see.

Another words, when you look at the menu or ask waiter about the menu, it is like making a GET request in software application. You are asking to see the information they have, without making an order or changing anything.

Explained POST request:

This will occur when restaurant customer decides on what he/she wants to eat/drink and places and order with the waiter.

Once you told to waiter what you want to order, for example Chicken quesadilla. In software terms, this is like when you fill out a form on the website and hit the submit button. In this moment you are sending a request(order) to the server.

Waiter(API) takes your order(request) to the kitchen(server) for meal preparation(processing).

Chef(Backend System) takes order and starts preparing the meal. Once meal is prepared, waiter(API) will bring it to your table. In software application, once the server has processed your POST request, it sends back the response to indicate that your request has been successfully processed.

Another words, when you order a meal, it's like making a POST request in software application. You are sending new information to the system, which get processed and after processing is completed you get the confirmation.

Explained PUT request:

Imagine you have ordered Chicken quesadilla but after 5mins you decide you want something else instead. So, you call the waiter over and tell him to replace the chicken quesadilla with calzone.

Waiter(API) takes your new order to kitchen(server). Kitchen(server) will understand difference between previous order and new one.

Chef(Backend system) prepares new order(calzone) from scratch, disregards the initial order of chicken quesadilla.
In software, a PUT request replaces existing data with the new data you provide.

Once the meal is prepared, waiter brings it to your table. In other terms, server has updated resource with new data provided, and the server has processed it successfully.

Explained PATCH request:

PUT and PATCH are very similar in it's nature. Key difference is that PATCH can make partial updates, while PUT is replacing entire resource with all data provided.

In so called body we send only those fields we are aiming to update. In our restaurant, a PATCH request is like when you want to make a small change to your order that you have already placed, without changing the entire order.

Let's say you have ordered calzone and after a while, you decide you want to add mushrooms in it. You call the waiter over and request just this one addition. This is like a PATCH request in a software application.

Waiter(API) takes order to kitchen(server), kitchen understands you are not changing entire order, just adding something to it. Chef(Backend system) then adds mushrooms to your calzone, without changing the rest of your order. Once order is processed successfully, waiter will bring it to your table.

Explained DELETE request:

This one is rather simple. A DELETE request is when you decide to cancel an order that you have already placed.

Imagine you have ordered calzone, but then you change your mind and decide that you don't want it anymore. You call the waiter over and him that you are cancelling your calzone order.

Waiter acting as API will go to the kitchen(server) and leave this request. Chef(Backend system) will pick it up and will remove this order. At the end, waiter will come to your table and confirm that your order has been successfully removed.

Conclusion:

In this restaurant analogy, each type of request customer makes represents a different way of interacting with the kitchen(server). Whether you are just looking at the menu, making an order, changing it completely, adding to it, or cancelling it altogether, each action has parallel in how software application communicates via API. Just as in a restaurant where your requests are handled with care to ensure satisfying experience, in software applications these requests are handled by APIs to ensure smooth and effective communication between different parts of the application, serving you with good experience.