Decoding APIs for Product Managers

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!

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.

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

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.

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.

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/