A Product Manager’s Guide to APIs

What are they and why are they important

Image by Fiverr

We live in a world where technology reigns and data presides at every corner. As users of many different products, we’re no longer looking for the best product to get the job done, we’re now looking for the product that gets the job done AND works seamlessly with all other products we use. Therefore, it has become increasingly important to understand tools that simplify workflows and integrate components to provide a seamless user experience for our customers. Since data has become abundant, innovative teams have grown exponentially better at forming these links and connections to simplify workflows via APIs.

What is an API?

An Application Programming Interface, or API, is in its simplest sense a technology that connects two systems.

Here’s an analogy explaining it:

You go to a large library and are looking for ‘The Da Vinci Code’ by Dan Brown. But the library is huge and you have no clue where to find this book. Luckily for you, you see the librarian at their desk and a catalog with the types of books you can borrow. You request for ‘The Da Vinci Code’ from their fiction list. The librarian walks through the labyrinth of shelves to find the book and brings it to you.

Photo by j zamora on Unsplash

In this analogy

• the library is the database — one of the systems involved
• the books are the data
• you are the requestor — the application/system looking for information
• the librarian is the API — they take the request back to the database and return information back to the requesting application
• the request for the book is the call made to the API
• the catalog represents the specific format the request has to follow so the API understands it
• the book you received from the librarian is the response

By Sachin Jain for ByteNBit

In the simplest of terms, that is what an API does: it acts as the interface between two applications and facilitates information transfer while ensuring speed and security. It is a developer-centric tool — APIs are built by and for developers as part of the application code, however, this doesn’t mean they can’t drive value for the end user.

How do they work?

Let’s take a real life example.

You are on LinkedIn and you are trying to find some companies in the fintech space. You type out your keywords (industry, location, etc.) and LinkedIn executes the search to display relevant results from its database of thousands of companies in less than a second. This request to look up all the relevant companies almost instantaneously is likely facilitated by LinkedIn’s Company Search API (which is also available for use by external applications).

This type of request-response interaction can occur within a product or with external products and is used to facilitate information transfer ranging from financial payments data to location data, in order to provide a seamless experience for the end user.

Why are they important to product managers?

APIs open up a world of opportunities to build a more-integrated product to provide more value for your users. As a product manager, it helps to understand the benefits and the constraints that also come with the technical solutions built/leveraged by the product team, so you can make and communicate product decisions and strategy effectively. I’m not saying you have to understand APIs to the point where you can dig right into the code — instead you should be able to understand the value it provides your user and business so that you can identify and test if there is a need for it and communicate WHY this is necessary to all stakeholders/partners of your product.

Using APIs built by others

I’ve created a really simple, short list of the ‘Good’ and the ‘Bad’ items to consider when thinking about using APIs built by others.

The Good:

• It can provide a well-integrated and simple experience for the user
• If you leverage other APIs, you can focus on building features that address the core need for your product, while maintaining a simple and complete flow for the user
• It can reduce the effort to implement specific features

The Bad:

• Some cost money (based on the volume of requests you’re making)
• You create a dependency on another system — if the other system changes their API call, you have to make changes on your end to ensure your user experience isn’t interrupted

Building an API for others to use

There are a few key items to consider before undertaking this:

• Is this something users want or need? If so, are they likely to use it? This can be validated quickly by talking to customers or even with landing pages to evaluate the demand
• What value is this driving for our business? Are we expecting an increase in revenue? or a higher conversion rate? It’s also important to ensure that we are targeting metrics in line with our product strategy and our organizational goals
• Can we even do this? Is our business ready to support the cost of building it out and also the cost of maintaining the infrastructure to provide this service for our users?

Implementation

Once you’ve identified the need for leveraging or building an API, it’s also important to understand how you break this down into user stories for implementation while maintaining focus on your user persona’s goal. It may help to split the user story into two — one for the API and one for the UI functionality/piece. However, you could include it all in a single user story and call out the API criteria specifically in the Acceptance Criteria. The approach should be discussed with the product team to see what works best for them.

Who is the user?

This could be developers, testers of an application or technical folks on specific internal teams. It is important to really understand and isolate your user and have a clearly defined persona for each type of user to provide context on their specific needs and goals.

For example — if your user is a developer, make sure you either define the specific type of developer (front end/back end/developer looking to incorporate payment functionality) or have a clearly defined user persona the team can refer to.

What is their need and their goal?

For this portion, you need to understand the functionality that is expected (create, read, update, delete) by the user and tie that back in to what the user is trying to achieve.

Your final user story could go something like this:

As a developer working on payment systems, I want to fetch the customer’s relevant financial data when I send a customer identifier, so that I have the information from the customer to process the financial transaction.

Acceptance Criteria

I’d include any mandatory fields that need to be a part of the API requests and the key fields that you need from the API response. If this connects in to the front end, it’s also important to call out those elements here to ensure its tackled by the team. If you’re integrating with an existing API then it’s best to read all the API documentation upfront and ensure it’s attached to the stories for everyone’s reference.

Another section to include would be API criteria that is not directly associated with the actual function of what the API is trying to achieve, but could impact the end customer. This could include the number of requests to be handled per unit of time, the time it takes to send out/receive a response, any authentication/authorization information expected by the API, limits on the volume of data sent in a single API call — it’s best to call this out explicitly and tackle this with the technical team, especially if these items can impact the end customer experience.

Few more things to learn about APIs…

Now this section includes more details that you could say are teetering on the edge of the more technical side of things. I’ve used this section to detail areas I’m familiar with through work and also explore areas new to me.

Public vs Private

APIs largely fall into 2 buckets: Public and Private.

Public — these are APIs open for use external to a company. Key examples are the Google Maps API to leverage Maps functionality in your product, Braintree API to leverage payments functionality in your product or the LinkedIn Company Search API to add company search functionality in your product. The goal is to be able to share information for use cases being tackled by other companies, that can end up benefitting your end user (eg. Open Banking in the world of financial data)

Private — these are APIs developed for internal use for developers/applications with specific access. Key examples are customer information APIs within a company that can be used by different business functions within that company for obtaining customer information pertaining to the problem they are tackling.

Types of APIs

I’ve only listed the two key types (there are other older formats that are not used as commonly today)

1. REST (Representational State Transfer) — this is currently the most common type of API. REST represents a specific API architecture and these APIs generally use HTTP functions to make/receive requests (with information typically being sent/received via JSON files). A key thing to note about REST APIs is that they are flexible in terms of the types of data they return/take and have a low bandwidth. There are 4 key HTTP functions these APIs are based on: POST, GET, PUT, DELETE (performing create, read, update and delete functions respectively)
2. SOAP (Simple Object Access Protocol) — this is an actual protocol. SOAP APIs generally use HTTP and XML. These APIs are often heavier in terms of bandwidth and payload.

Webhooks

Webhooks get a special mention because they can be considered a special type of API — the simplest way to describe them is a “reverse” API. With APIs, the data transfer will not happen unless a request is made explicitly; webhooks on the other hand trigger the data transfer based on an event (such as a payment being received, an update to a user’s feed, etc.) which can be really beneficial to automatically trigger a downstream set of events.

Where do we go from here?

This was just a short intro into the world of APIs and how it could play into conversations with your stakeholders as a Product Manager. Hopefully, it’s equipped you to identify opportunities to optimize your product and also understand the numerous items the product team has to consider when dealing with APIs.

There’s still a lot more that comes into play when building or using APIs, ranging from understanding API documentation to figuring out how you authenticate users of your API, and this means there’s a lot to be learnt if you’re interested. Time to dive right into it!

If you want to build an API…

I took the last two days to build a simple REST API based on Python and Flask that leverages the GET and POST request methods. I’ve listed out some great resources below that should definitely help you get up and running and experimenting on your own!

Creating Web APIs with Python and Flask

REST API vs Web API (vs SOAP API) [What's the Difference?] | RapidAPI

Designing a RESTful API with Python and Flask

The curl guide to HTTP requests

Quickstart - Flask Documentation (1.1.x)

Additional great reads

Understanding API-Based Platforms: A Guide For Product Managers - Smashing Magazine

APIs Explained for Product Managers - Department of Product

References

• What is an API? Everything you need to know — Adam Hughes
• REST vs Web (vs SOAP) API (Sep 2020)