What are APIs? — iago, wtf?!

You could say that API is a term that's already part of any Product Manager's daily life. I think one of the phrases I use the most is "but can't we just create an API and hit an endpoint to grab this info?". Okay, it's not in my top 10 most-used lines, but it pops up a few times a quarter.

But what are APIs, really?

In this short series I'll try to bring some basic concepts I've learned throughout my career and through my hobbies to help new PMs or just to have it on record for future reference. Today we're talking about APIs, focusing on REST.

Architecture and APIs.

Pretty much every digital product works with three main building blocks: the client/interface, a server, and a database.

The client/interface is where the user normally interacts: a website, a mobile app, a .exe on the computer, etc.
The server is a computer connected to the internet that will process whatever you ask of it. (one day I'll write one of these posts about servers/internet)
The database is where any information you want to store is kept. Think of it as a beautiful .csv or an Excel spreadsheet: columns and values.

When you search for something on MercadoLivre, the site rendered on your computer sends a request to the server. This request/communication is made via an application programming interface, an API.

How does an API work?

APIs are everywhere on the internet. There are 3 types of them:

Public: APIs that can be used and accessed by anyone. It means any developer can use them and build stuff with them.
Private: Used internally within companies; say a company has an application that communicates with another internal application with sensitive data, a private API makes this communication happen securely and isn't accessible to outsiders.
Partner: A middle ground between the two above, usually these are company APIs that allow solutions to be built but require a partnership level. Twitter, for example, had an API that allowed other apps to send and read tweets and developers were required to be partners and make payments proportional to API usage. Unfortunately, Twitter killed that a few months ago.

Now, how does an API actually work?

Breaking it down into steps, it goes more or less like this:

When you go to MercadoLivre and type "iPhone" in the search, the site sends a request to the API, let's say api.mercadolivre.com, asking for all products named iPhone.
The server processes the request and runs a "query" on the database.
The database returns to the server a listing of all products that are iPhone 15.
The server grabs that listing and sends it to the site/client.

And then you'll finally see a list of iPhones on your screen.

The server isn't the API or vice versa. The API is an application running on the server. It's a set of actions available to the client. In this case, the listing action is one of the features of the API running on the server.

These actions are what we call endpoints. Imagine that besides needing to list products, the MercadoLivre API also needs to inform the shipping cost, the seller's reputation, etc. Each of these actions is an endpoint.

Examples:

Let's say you listed the iPhones using the listing endpoint.
- A request for iPhone is sent to api.mercadolivre.com/listing, which will return the product listing for that term.
Now you want to calculate shipping.
- A request is sent with your ZIP code to api.mercadolivre.com/frete, which returns the R$45 shipping cost.

You get the idea. So we're saying the API lives at api.mercadolivre.com and the endpoint is /listing.

POST and GET

There are several types of requests that can be made to an API; the two main and most common ones are POST and GET.

GET requests are more simplified and less secure requests, because as you'll see below the entire request is visible in the URL. In the previous example, if you go to MercadoLivre and want the iPhone listing. It's a GET request to the /linsting endpoint on the API that will deliver the listing to you. GET requests send information in the URL as parameters.

https://api.mercadolivre.com/listing?product=iphone

POST requests are requests that submit data to the server in the request body and not in the URL. So, when you send a POST to an endpoint you send what we call a body, which can be a set of parameters and values. POST is commonly used in requests that require more information because GET has a limit of 2,048 characters. Below is an example of a POST with a cart built on MercadoLivre.

https://api.mercadolivre.com/cart

Body:

{ "product": "Apple iPhone 15", "coupon": "desconto10", "cep": "50050450", "paymentmethod": "Pix" }

Types of APIs

There are different types of API specifications. I won't go into detail because it's a deeper level, but these three are worth highlighting:

REST: The most common one, it uses the http/web protocol to receive requests. It's the one that uses the GET and POST requests above and what we focused on in this text.
SOAP: An older specification that uses only XML as its format.
GraphQL: A very recent specification created at Facebook/META, it focuses on efficiency by bringing only the requested data and nothing else, besides allowing data to be extracted from multiple sources using just one request. It can also have mutations to work like a POST creating resources.

If you want to dive deeper into any of these topics, I've left some links at the end of the post that I used in the past to study them.

Conclusion

APIs are applications that run on servers and execute actions through endpoints; they can be public or private. APIs are everywhere on the internet and in products. They're part of any Product Manager's reality, and it's important to have basic knowledge of them because it will make communication with developers a lot easier and maybe even help find possible solutions to certain problems.

disclaimer: This text is a simplification meant to present initial technology concepts to a non-technical audience, such as Product Managers or the curious. The author is not a developer, and the information provided is generalized to facilitate initial understanding. It is recommended to consult additional sources for a more complete and accurate understanding.

Useful links: