A Product Manager and a Software Engineer walk into a bar.
They look intoĀ the menuĀ and order their food and drinks. The Product Manager has few drinks and rants to the Engineer asking about the new fad called āAPIā.
The tipsy Engineer smiles when the waiter serves the order and tells the PM that he just made an API call.
The confused PMĀ asksĀ how?
The Engineer takes a pen and a napkin, ready to answer and explain the curious PM.
EngineerĀ ā Follow me as I tell you a tale of a person, an exclusive restaurant and a chef/owner to explain you what an API is and how it works!
PM āĀ Oh wow! Letās get this party started!
Authentication
EngineerĀ ā Imagine you are going to this fancy restaurant which is exclusive to members alone (letās say a Yacht Club Restaurant that allows you to dine in only if you have a Yacht Club membership). You get a membership for the club and hence can access the restaurant dine in.
PMĀ ā So what does that mean in API sense?
EngineerĀ ā This means that like the fancy restaurant mentioned above,Ā APIs have some exclusivity as to who can use it.Ā If you want to enter the restaurant, you will need to have a valid membership card along with ID proof for the Yacht Club restaurant to admit you inside.Ā In technical terminlology,Ā you will needĀ API keys or tokenĀ to get authenticated to use the API.
Endpoint
EngineerĀ ā Ok bruh! Now that you are an exclusive member of the imaginary Yacht Club, will you take me to the imaginary restaurant?
PMĀ ā Yes of course! Mind telling me the address and directions to this imaginary restaurant?
EngineerĀ āĀ Haha!Ā This address is what they call an āEndpointā!
Illustration: This is how an endpoint looks like āĀ http://theyachtrestaurant.com/Menu
Method, Request and Response
EngineerĀ ā So, now that we have landed in the imaginary Yacht Club restaurant, what do you want to do?
PMĀ ā Isnāt it obvious? Letās order food!
EngineerĀ ā Perfect! So start describing your actions in the restaurant and I will justify it with API analogy.
PMĀ ā OK cool! Going along this storylike, firstly I would like to see what all they serve!
EngineerĀ ā Great. You have just used a āGet Methodā.
PMĀ ā Dude, can you first tell me what method is?
EngineerĀ āĀ A āMethodā is nothing but a āVerbā or an āActionā you ask the API to perform.Ā The API isnāt as intelligent as you are Mr. PM, so we need to provide some instructions.Ā We have to be very courteous and āRequestā the API to do something for us.Ā For APIs to work, you will need to send some instructions in the āRequestā payload.Ā Once the āRequestā is processed, you get a āResponseā payload from the API that provides you the output and outcome information.
PMĀ ā So in the example where I ask the waiter to get menu so that I can see what they serve, how would you break it into the API terminology?
EngineerĀ āĀ Here you go:
a.Ā Method = Get
In API analogyĀ the GET method is used to retreive data from a server at the specified resource.Ā In this scenario, you had asked the waiter to get you the list of items served in the restaurant.
Request:Ā It means that you are asking for some information from a database.Ā In this case you have requested to see the list of items served in the restaurant
Response:Ā The waiter serves you the menu.Ā The outcome of the response is that you get a menu which shows you the list of items served in the restaurant.
Let me do an illustration of the API:
PMĀ ā This is great. But why isnāt the request body there?
EngineerĀ ā Rules, my lad! As a rule āGetā method endpoints will have āQuery Parametersā which are nothing but the request body put in the URL.
EngineerĀ ā Rules, my lad! As a rule āGetā method endpoints will have āQuery Parametersā which are nothing but the request body put in the URL.
PM- Thank you comrade for the explanation. Would you like to order dinner and then go home if we are done explaining about APIs?
EngineerĀ ā My friend, we have barely scratched the surface. Let me dig deeper into API concepts.
We have spoken a bit about āGetā call. But there other methods which I would describe the scenario and API analogy for:
b.Ā MethodĀ =Ā Post:
In the imaginary Yacht Club restaurant, you did not find any food to your liking. You call the chef /owner of the restaurant and request for a customized or a new dish. Does the humble chef ask what you would like to have? You start describing your famous āVegan Burgerā recipe that your mom cooked for you. The chef makes the vegan burger and serves it to you. The smell of the burger is so inviting that it makes the neighbouring tablesĀ curious! They call the chef and ask to be served the same dish.
The chef decides to put this new item to the menu!
In this scenario,Ā the act of putting a new item to the menu is called āPostā. How to achieve it is by courteously requesting it!
Request:Ā The chef will add a new item called āVegan Burgerā. The request should contain the item name along with the description and price to be posted to the menu.
Response:Ā The outcome would be to see the confirmation that āVegan Burgerā along with āDescriptionā and āPriceā is posted and visible on the menu
PMĀ ā OK, what is content type and Jason Statham doing in the example?
EngineerĀ āĀ Content Type is a part of the header. Before you ask me what anĀ header is, it defines the metadata of the request and response information. In this example, the header is containing the āContent-Typeā and āAcceptā which tells us how the request and response data format should be. The Jason Statham in your language or āJSONā in the technical terms is one of the type of data format which means how the content would look!
c.Ā Method = Put
The āVegan Burgerā is a big hit in the restaurant, but the customerās complain about the exorbitant price. The humble chef / owner decides to slash the price by few dollars.
In this scenario,Ā the act of updating an existing item in the menu is called āPutā.
Request:Ā The chef enters a new price for the item āVegan burgerā.Ā The request payload should contain the reference of the item you are updating and the parameters that require the update along with the values.
Response:Ā The outcome would be to see the updated price in the menu for āVegan Burgerā
d.Ā Method = Delete
With the heavy demand in āVegan Burgerā, the chef decides to remove an item from the menu.
The act of removing an item is called āDeleteā in API terminology
Request:Ā The chef will request to remove āCaviarā from the menu. The request payload should contain the item name amongst other details to be removed from the menu.
Response:Ā The outcome would be to see the confirmation that āCaviarāis no longer visible on the menu.
API Status Codes and Error Messages
PMĀ ā Wow! That was pretty elaborate. I like the fact that the api does all the things you want them to do.
EngineerĀ ā Haha! In your dreams buddy!Ā APIs are not always faithful. They are prone to error sometimes.
PMĀ āĀ So how would I know when an errorĀ occurred, how it occurred and what is the indication for me to understand?
EngineerĀ āĀ This brings us to our next concept called āresponse codesāĀ .
2xx :Ā means that your request was successful.
3xxĀ :Ā Imagine you drive up to the imaginary Yacht Club Restaurant to find a notice a signboard that says it has moved to a new address and the hotel representative telling you the direction of the new location directions.Ā In API terms, it means that the request is redirected to another URL.
4xx:Ā You drive up to theĀ restaurantĀ and order for āCaviarā only to find that it is no longer served in the restaurant!Ā This is equivalent to the Client errors (unauthorized, forbidden, page not found).
5xx:Ā In this case you are the victim! You had ordered the vegan burger, but the queue was long, and your item took a long time to be made. You left the resto in full rage.In API terms it means Service not available or gateway timeout.
For more details on response codes check the link āĀ https://http.cat/
Img Source: Saturday Evening Post (saturdayeveningpost.com)