What Every Product Manager Should Know About APIs
This article was originally posted on Product Oversee.
https://productoversee.com/o-que-todo-product-manager-precisa-saber-sobre-as-apis/
APIs (application programming interfaces) are how software talks to each other and are therefore a key technology in connecting systems.
These interfaces allow development teams to use data, functions, and applications to build new products simply.
As a Product Manager, it is crucial to understand how APIs work and their huge potential within your team or company.
Why use APIs?
APIs can be the key for organizations to quickly expand into new contexts or adapt to new markets with considerably reduced effort.
Through them, teams can utilize existing infrastructure and reduce development time from months to weeks.
Here are the most important concepts you need to know about APIs as a Product Manager. With this understanding, you will have a solid foundation to talk about APIs with confidence to your stakeholders and your team.
Public and Internal APIs
Before we start talking about how the APIs work, we need to make a small differentiation. We can separate APIs into two groups, the public ones, and the internal ones.
Internal APIs are those used by your company’s software, for example, to communicate with the different microservices built by your engineering team.
They are used only in the context of the company to satisfy the needs of its own applications, such as transferring data internally.
Public APIs, on the other hand, are designed to be shared with the outside world. With them, developers can build applications to take advantage of the information and functionality present there.
Slack is an example of a company that has a public API. There you can build an application that sends messages, generates alerts, and creates groups on the platform.
- Internal APIs: built by the team to satisfy particular application needs;
- Public APIs: developed to allow (external) developers to build applications based on what was made available.
Requests and responses
In simple terms, APIs work using “requests” and “responses”. The requests are us interacting with the API, and the responses are the result of that interaction.
Let’s take an example. Using the AccuWeather API, we are able to request information about the weather in a certain region. To do this, the following activities must be performed:
You, as the API user, send a request to the AccuWeather API (interaction);
- In the body of this request, you tell the API which region you want to receive the weather information. How this description is conveyed should be described in the API documentation (we’ll get to that in a moment);
- AccuWeather returns the requested information via a message in the format of a “JSON” (response).
The API documentation will specify how information is to be passed and how a response can be understood by the system.
HTTP Methods
It is necessary to specify what is called an HTTP method in the requests we make to an API.
These methods will be responsible for indicating what action will be performed for a given resource in the interaction (whether we just want to get or edit a resource, for example).
You don’t need to learn all HTTP methods, in the most used version currently, 1.1, we have 9 methods that have different use cases.
The methods most used by a product person are POST and GET, which allow you to create or get information.
Here is a summary of the most common HTTP methods:
- POST: used to create new resources. For example, if we wanted to create a new text message using the Slack public API, we would use the POST method, since this is how you create new resources (in this example, the resource is the message);
- GET: are used only to read data and not to modify it. This means that they are considered secure. For example, in the AccuWeather API, GET is used to get the weather information for a region;
- PUT: used to update/replace data. For example, updating a user’s email address.
There are others, but we will concentrate only on these, since they are the most common. If you know them, you know enough.
Endpoints
An endpoint is a location at which an API connects with software programs. In other words, endpoints are the specific digital locations where requests are made and responses are received by a program or user that is interacting with the API.
Let’s take an example of the AccuWeather public API endpoint.
GET http://dataservice.accuweather.com/currentconditions/v1/{locationKey}
In this endpoint, called currentconditions, the user can make a GET type request to request the current conditions data for a specific location.
In this example, we have locationKey as a parameter passed by the user in the request. It serves as a way to specify to the API which region we are looking for information from.
It is worth noting that the same endpoint can work with more than one type of HTTP method.
The use of multiple methods is not simultaneous (you cannot do a GET and a POST in the same request), but in some cases, you can get and/or edit resources within the same endpoint.
Response Codes
During the process of interacting with an API, you may receive different types of messages. These response codes are used to indicate the success or failure of a request. In general:
- Codes in the 200 range indicate success;
- Codes in the 400 range indicate an error based on the information provided (for example, a required parameter was not sent);
- Codes in the 500 range indicate an error on the API servers.
The messages that appear in each case vary depending on the API. The details of the messages and the application use cases are described in the API documentation (usually where it talks about error handling).
Authentication and authorization
Most APIs require some sort of user authentication before making a request to their services.
In the case of public APIs, users usually have access to a credential that will be added to the request when it is sent. These credentials act as an identifier for the person or company that is interacting with a particular service.
For example, when I request the weather data for my region from AccuWeather’s API, the application knows that it is me who is requesting this information and not someone else.
In addition, authentication methods also serve to limit or grant access to certain API features (authorization).
If we cannot allow any group of people to access or edit certain data available through the application, we create a limitation for those through their access credentials.
This way, when this group tries to do an action that they are not authorized to do, the API will send an error message in response to that interaction.
Overall:
- Authentication: demonstrates to the API who is the user that is interacting with its services. Most of the time, a user’s authentication is composed of: user, password, access token;
- Authorization: is a definition, developed by the team that built the API, about what the user groups are allowed or not allowed to do in their interactions with the services there.
API Documentation
The documentation ends up being the product people’s main point of contact with the APIs themselves. It’s where all the available functionality will be listed, and how interactions with the application can happen.
In some cases, we may have places in the documentation where requests can be made directly from the browser (usually this is on a page called API Reference).
This page shows how the request will be assembled and how the response will be returned. In addition, the documentation makes it clear what the limits are for each type of access and/or plan.
In the case of APIs that work across plans, there should be some sort of table with what each plan can access (and the number of requests that can be made in a given time period).
Finally, the documentation should include the parameters that can (or must) be passed in the requests. What information is required and how it needs to be sent within the service.
In the AccuWeather endpoint example, the documentation makes it clear how the parameter (locationKey) should be passed so that the API can understand what the user wants.
In this way, the user and the API are able to communicate in the “same language” and both get what they want.
What to expect to find in documentation:
- Authentication instructions: how you should prove to the API who you are when interacting with services;
- Endpoints: which endpoints can be accessed, what resource they each provide, and which HTTP method(s) they use;
- Resources: what is available through the API. If we go back to the Slack API example, the documentation should explain that through it you can send messages, create groups, generate alerts, and request user information, for example;
- Request format: how you should send requests and which parameters can (or should) be passed;
- Response format: how the API will respond to your requests. At this point, it is worth noting that an API can respond in formats other than JSON (which we talked about in the AccuWeather example). This distinction is based on the architecture of the API, which can be REST, RPC, or SOAP, and the purpose of the application itself;
- Response codes: what response codes are present and how to handle possible errors received.
So how can APIs help you on a day-to-day basis?
APIs have the ability to provide your team with the potential to create products and validate hypotheses faster since they will be using existing infrastructure.
In general, as a product person, you can look at existing APIs on the market (public) as possible opportunities to do testing or grow a product you already have.
- How can an API help me optimize a process?
- Do I need to build my own infrastructure or is it worth using a third-party infrastructure?
- How does this affect my business model?
These are valid questions to ask when you start considering the use of public APIs in your products.
Finally, building APIs as a way to scale a business has been a widely used practice by players in different markets.
Outsourcing your infrastructure by opening up your services to other companies brings with it the opportunity to enter a new market (B2B, for example) and grow exponentially, but this is a subject for another conversation.
Thanks!]
Tech PM is a newsletter for you who are looking to develop technically in product management and develop yourself further.
In this newsletter, you will receive topics such as:
- Topics for non-technical people
- API product developments
- Tips for technical product development
- Career development
Who am I?
I am Henrique Maltez, a product person in Brazil, and someone who has watched 26% of the top 250 IMDb (at the time of writing this text correctly).
I hope I can help you with what I know and learn a little more every day.
Feel free to contact me if you need help with anything.