A to Z of API's for Product Managers
APIs, endpoints, query parameters, error codes and much more!
Want to learn APIs as a Product Manager? Please check out my 3-week long online course (Tech for Product Managers) - https://www.xplainerr.com/cohorts/api-for-pms (45% OFF)
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 :-
Why do we even need APIs in the first instance?
What exactly do we mean by an API?
What is request-response cycle?
How to read API documentation? What are end-points & query parameters?
What are the various error codes in API handling?
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➖
Your e-commerce app ➖ Can you collect my payment?
Razorpay ➖ Sure! What's the amount I need to collect?
Your E-commerce app ➖999.
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.
Want to learn APIs as a Product Manager? Please check out my 6 hour long online course (API for Product Managers) - https://www.xplainerr.com/cohorts/api-for-pms (45% OFF)
