A to Z of API's for Product Managers

APIs, endpoints, query parameters, error codes and much more!

This blog is under paywall. Please check full course (API & Webhooks for Product Managers) here - xplainerr.com/courses/api-for-pm

Welcome to my second newsletter. This one is on API’s! (And this will be a 12-minute read :p)

There is a joke that my one of my (developer) friend always use to tell me - If a Product Manager knows APIs, then I know that they understand technology.

In this newsletter, I will try to explain what an API is? I will also deep dive into :-

1. Why do we even need APIs in the first instance?

2. What exactly do we mean by an API?

3. What is request-response cycle?

4. How to read API documentation? What are end-points & query parameters?

5. What are the various error codes in API handling?

6. How can we secure APIs? What is Oauth?

And a lot many other things!

---

1. Why do we even need APIs in the first instance?

This is gonna be quite interesting.

Suppose you are building an e-commerce app like Amazon. (Oh! common, I mean you can easily build an e-commerce website. There's no rocket science)

So, when your customer selects an item to buy; she is then landed on the checkout page. What's next? You would want to collect payments. Now, building a system to collect payments is indeed a cumbersome task because you need a lot of tech efforts and compliance adherence from the government, RBI, and banks. Which you would obviously not want to do.

Instead, you find that Razorpay can do that on your behalf (that is collecting payments from your customers). You are excited but there are still a couple of problems.

• Your e-commerce platform is one system and Razorpay is another system. How do you connect two systems so that they can communicate with one another?

• One step further, Razorpay doesn't know how much is the payment amount should they collect? Is it 499 or 999 or something else? They expect you (I mean your e-commerce app to give that detail)

• Also, you would want to know one more thing. Once, Razorpay has tried collecting the payment; was it successful or not? If it was; you can ask your warehouse team to ship it. (Yeahh!)

  

Can you see how beautifully these two systems are talking to one another?

But the question is how are they talking to one another? The answer is they are talking to one another through a piece of code.

This piece of code through which two systems (applications) talk to one another is called as API. wOw!

One more beauty of APIs

Have you noticed it?

When both of these systems were talking to one another (I mean your Amazon & Razorpay) they only asked each other relevant information➖

1. Your e-commerce app ➖ Can you collect my payment?

2. Razorpay ➖ Sure! What's the amount I need to collect?

3. Your E-commerce app ➖999.

4. Razorpay ➖ On it! (Few sec later) The payment is done!

You didn't expose your entire system to Razorpay nor did Razorpay expose your entire system to you. You and Razorpay only passed data that were relevant to both of you. (No bakwass!)

---

I share my not so ‘important’ opinion on product, tech, design, venture capital, and human psychology on Xplainerr here. Do subscribe - no spam, ever!

---

2. What's an API?

Officially! API stands for Application Programming Interface. (Reading the definition of API on Wikipedia can give a nightmare.)

But we have seen a very simple definition (in the Amazon - Razorpay) example.

APIs are a piece of code through which two systems (applications) talk to one another.

Let's see one more analogy. Hope this makes API crystal clear.

2.1 Dominos analogy

Let's take a famous example of the customer-waiter-restaurant model (quoted in every reference book) to understand API in simple terms.

If you go to a restaurant (as a customer), you are not allowed to enter the kitchen. You only need to know what is available and what can you order. For that, you have the menu card at your table. After looking at the menu, you can make an order to the waiter, who passes it to the kitchen and delivers what you have asked for.

The waiter can only deliver what the kitchen can provide.

So, to sum up, you can think of various analogies:-

• Kitchen - the database/server that serves you food

• Waiter - a middleman that serves food from the database/server (kitchen) to you (it’s the API)

• You - an external system that wants the food (data) and made the request to the waiter (API)

• Menu - a document that lets you know what can you order, food’s flavour, price, etc! (API Documentation)

• Order - a request for the food that you have made

• Food - the response that you have got (pizza)

So, yeah! You and the kitchen are two separate systems and both of you are able to communicate through waiter.

Think waiter. Think API. Both are analogous.

2.2 Rest API

When you hear or read about APIs, you'll almost always see the term REST associated with it. Remember, REST is just a standard for APIs, and by now almost all APIs conform to the REST standard.

REST is a set of rules that developers follow when they create their API.

When an API follows the rule of Representational State Transfer; they are called REST API.

One of these rules states that you should be able to get a piece of data (called a resource) when you hit on a specific URL.

REST determines how the API looks like. I will not go into the rest standards and feature in detail here but you can think of it as a set of rules that APIs follow these days.

---

3. Request-response cycle

We saw a glimpse of request & response in our Dominos analogy. What was that?

Question - Can you recollect & say out loud?

The piece of data that you send to the server is called as request.

Here, by you, I mean, your web browser. Btw! You in the tech world is called as client.

The piece of data that you get back from the server is called as response.

3.1 Types of request

You must be wondering what type of things I can ask from the server?

You can make different types of requests to the server➖ give me a piece of data, upload my data to the server, edit my data on the server, delete my data on the server.

Fun fact! All of these requests are named after a verb.

The four common types of request are ➖ GET, PUT, POST, DELETE

• GET ➖ You make a GET request to get some piece of data from the server

• POST ➖You make a POST request to add a new piece of data to the server

• PUT ➖ You make a PUT request to edit the existing piece of data on the server

• DELETE ➖ You make a delete request to delete a piece of data on the server

LinkedIn example

Let's take a few use cases from LinkedIn and understand the analogy (better)

• What if you want to search my profile? You will type my name in the search bar & press enter. The moment you press enter; you are making a GET request to the server to get details of my profile.

• When you are adding a new post on LI; you are making a POST request to add the data to the server.

• When you are making an edit to your existing post & click on save, you are making a PUT request to the LinkedIn server to update the existing piece of information.

---

4. How to work with an API?

You always need to check the API documentation (first) to learn how to play around with the API.

To work with an API; you need to do the following things ➖

• Read the API documentation carefully

• Test the response through Postman

• Implement through code

4.1 Exploring an API documentation

Let's say you want to integrate Google signup API on your site (i.e. you want that your users can signup using their Google account)

What would be step one? The first step would be to visit the APIs documentation. API documentation is the starting point when it comes to working with APIs.

Remember! A good API should have detailed documentation explaining how to work with it.

• It should describe the basics of what the API does, what type of data you can get from it.

• It should explain the requirements for using the API. Is it free or paid? Does it require you to register and obtain a key?

• It should also provide examples of how to make requests and the responses returned.

• And most importantly, for actually working with the API, it should provide you with endpoints and parameters.

4.2 Endpoints

What if you want to talk to me? You will have to dial my phone number +91-98xxxxxxxx

What if you want to talk to an API? You will have to connect to a specific location! That specific location is an endpoint.

Endpoints tell you the different places you can connect to an API.

They are URLs and the end of each URL connects you to specific data options from the API.

Take a look back to flipkart.com. What if you want to view a specific catalog like television, mobile, AC, etc?

As soon as you tap on the product you are interested to buy; you are redirected to a URL. Those URLs are the end-points.

• flipkart.com/tv

• flipkart.com/mobile

• flipkart.com/ac

4.3 Query Parameters

Now once you have tapped on the product you are looking to buy; what if you want to see products of a particular brand only.

You would most probably apply a brand filter. What happens next?

As soon as you apply the brand filter (say LG); a request is made to the server again & now you can only see the TV of the LG brand only.

Parameters allow you to more narrowly define or filter the response that you get.

They're added onto the URL following the endpoint.

Parameters are denoted by a question mark.

• flipkart.com/tv?brand=lg

• flipkart.com/tv?brand=lg&ratings=4+

Note ➖ You may also see forward slashes used for parameters on some websites.

• flipkart.com/tv/brand=lg/ratings=4+

4.4 Sample API Documentation

https://drive.google.com/file/d/1F3IKpbYee2MClDhZ1-BdUGXnE_9UmgCz/view?usp=sharing

4.5 Exploring APIs with Postman

The first step while integrating a third-party API on your website; is to test how it works.

For testing how APIs works, you can use postman. Through postman, you can request a piece of data & get the response (whenever you want)

Postman is a popular API client that makes it easy for developers to create, share, test, and document APIs.

Note: You can also access APIs and request data from the APIs using the command line.

---

Loving reading this content on APIs? I hope you won’t mind showing a small token of appreciation!

Do you know? You can contribute as low as ₹ 89. Help me to make my free content accessible for all! Please show your ❤️ here.

---

5. Error handling

5.1 Response status code

Throughout this newsletter, we've been discussing only with requests. What if we made the wrong request?

When we make a wrong request, we will get an error code. Chances are, that you must have faced one of the most popular status codes when you typed the wrong link — 404

So, by understanding the status code you can immediately tell what’s happened to your request.

There are four groups of status codes ➖

Within each group, there are specific numbers too, that gives us more details about the responses but really knowing just the four general groups, is usually enough.

• Status codes in the 200s tell us everything is okay. (i.e. we made the right request & got the correct response)

• 300 status codes tell us that we've been redirected to the appropriate resource.

• 400 status codes tell us that there was a problem on our end. (Something wrong with our request.)

• And then, 500 status codes tell us that there's something wrong on the end of the server.

---

6. Securing APIs via Oauth

6.1 Why do we need Oauth in the first place?

Let's go back to 2000s. What if you want to login into Facebook? They would ask you to enter your Gmail user_name & password! Bizaareee!

And you would be more than happy to give your Gmail user_name & password.

Why? As you would want Facebook to have access to your Google contacts ( Facebook can recommend you more friends to add, tell you about your friends birthday’s) and so on.

But in the quest; you are giving Facebook not only access to your Google contacts but your Gmail too (Facebook can read your emails & what not)

Then what do you wish for? You wish to only give your Google contacts access to Facebook without letting FB know your Google account user_name & password. Something like this!

Oauth was created for this particular purpose.

It allows you to give access to an application (say FB) to access (some & not entire) data without giving your password!

As you can see that (in the 2000s) a lot of developers were facing this problem; when working with APIs. So, developers came together with an open standard for authorization known as Oauth!

6.2 Oauth as hotel key card analogy

When you go to a hotel check-in; you are given a card at the reception to open your door.

The card is the authorization for you to open the door and use the room.

• Receptionist ➖ Authorization Server

• Card ➖ Access Token

• Door lock ➖ API (also called as resource server)

Note ➖ The door doesn't care about the card (i.e. who owns the card)! Anyone who has the card can open the door. Similarly, Oauth only cares about authorization & not authentication. Anyone who has the access token can access the server.

It's for the receptionist to decide - Is the card given to the right person?

Cut short, Oauth is only one authorization but not authentication.

6.3 Authentication vs authorization

6.4 How does Oauth works?

---

Hope you liked my post on APIs. :)

If you loved my content on APIs and found this valuable, I hope you won’t mind showing a small token of appreciation!

Do you know? You can contribute as low as ₹ 89. Help me to make my free content accessible for all! Please show your ❤️ here.

OR

Are you looking to break into product management but don’t know how?

I provide detailed guidance on how to break into product management - how to make your resume, how to prepare for interviews, and find relevant opportunities. ❤️

Why spend ₹ 50,000+ for a product management course? Why not book a slot with me at ₹ 999 and get personalized mentorship?

---

BTW, I also do regular shit-posting on Twitter here:- https://twitter.com/venkyHQ! If you have any piece of feedback/advice; do share it with me!

Let’s stay connected :) And if you have come this far, what is stopping you to subscribe to this newsletter?