Tech basics for product managers: API

A modern product manager builds only what is needed and, for the rest… integrates with ready-made. To take advantage of the 1000s API around us, a PM should understand the basics of API structure: endpoint, input, and output.

Buying coffee as an API call

API is a way to ask some system to do work for you. You give something as an input and receive the answer as an output. Whatever the system did in between to get the results doesn’t bother you — this is the point.

For example, when ordering a coffee, you exchange money and coffee choice (input) on the cup of coffee (output). You don’t care too much about how this coffee was delivered from the sorting center and which shelf it was placed in the storage room — but you do care about the quality of the result in your coffee cup. This is how the API documentation for the coffee purchase might look like:

# Input Parameters:
- Coffee type: "Latte", "Black", "Cappuccino"
- Milk choice: "None", "Regular", "Coconut", "Oat"
- Money: credit card or cash

# Output Parameters:
- Coffee cup
- Exchange: if applicable

# Potential errors
- Milk choice is not available (e.g. oat milk is out)
- We lost your order (e.g. paper with your name slipped to the floor)
- Coffee is too cold (e.g. barista forgot to heat up the milk)
- No change available (e.g. no way to buy 3.75$ coffee using 100$ banknote)

Notice that this simple exercise already forced us to consider a “contract” between a client and a service provider (in this case, a customer and a coffee bar). For example, now we clearly see the minimal requirements from a service provider to do its job (type of coffee, milk, and some money). A product manager can build on top of it by introducing new parameter extras:

# Input Parameters:
- Coffee type: "Latte", "Black", "Cappuccino"
- Milk choice: "None", "Regular", "Coconut", "Oat"
- Extras: "Syrop", "Creme", "Icecream"
- Money: credit card or cash

Or maybe later, they can think of a sustainable option “in-my-own-cup,” which saves a buyer 40 cents:

# Input Parameters:
- Coffee type: "Latte", "Black", "Cappuccino"
- Milk choice: "None", "Regular", "Coconut", "Oat"
- Extras: "Syrop", "Creme", "Icecream"
- In-my-cup: yes/no (reduces price by 40 cents)
- Money: credit card or cash

Why is it useful for a PM?

Notice how we moved from an abstract “buying a coffee” to a very clear set of rules: what comes in, what is returned, and what can go wrong. A PM can now align all stakeholders around this thinking because things are clearly written. When things are written, a juicy discussion can start:

For example, the supply department can review the contract and mention that they do not have oat milk but soya instead.
The financial department can immediately ban cash payment methods and ask a PM to switch to cards only. Later, they might introduce another payment method, “punch cards,” a mini version of the coffee bar loyalty program.
Developers can mention that “Syrop logic” is a bit shaky, so it might happen that a customer sometimes ends up with creme in their cup instead. So you, as a PM, should decide whether to wait until they fix it (they need two quarters for that, hehe) or remove it from the API contract.

After a healthy debate, all stakeholders are aligned — this is exactly what a product manager should strive for. Now, a team can implement the solution — the ball goes to their side of the court.

Integrating with the Weather API

If you are still unsure how it all comes together, I recommend calling a meme-generating API yourself on the free simulator here—it is easier than it sounds.

Now that we understand the basics of the API, let’s apply it to a situation PMs often find themselves in— a search for functionality their product needs, but the one they don’t want to build themselves.

Let’s imagine you are starting an app for runners and focusing customer value around useful running statistics, route building, sportswear, and health check upsells. You’d also like to integrate weather forecasts into your experience (not everyone enjoys running in the rain), but (hopefully) you are not planning to delve into weather modeling yourself — it will take you years and maybe decades to figure out. This is where API integration is useful: we pay a small fee, outsource the feature we need, and keep the laser focus on our core value.

So, you googled a bit and found this documentation of (paid) weather API:

# Input Parameters:
- City name: e.g. "New York City"
- Date/Time: e.g. "2024-02-08 15:00:00"
# Output Parameters:
- Temperature: e.g. 25°C
- Weather Condition: (e.g., sunny, rainy, cloudy)
- Precipitation: "20% chance of rain"
 
# Potential errors
- Location is unknown
- Date/time in the past

What does it tell you right away? You quickly understand quite a lot after 30 seconds of reading: you can pass the city name, date/time, and get back the temperature in Celsius plus weather conditions

It also tells you that:

Your customers will have problems in suburban locations further away from cities (because API doesn’t support plain coordinates)
The temperature is in Celsius only (US customers will suffer unless you do something)
It says nothing about wind (which can be not okay for runners if the wind is stronger than a certain value)

This is enough to either set a task for your team (or yourself) to integrate with this API or continue searching and finding something else. As a leader, you did this analysis in a few minutes without even talking to the techies! Look at you! Then, the user story to your developers can look like this:

I would like to get a weather forecast for the next 2 hours in the location user-specified (if nothing — use geolocation): temperature, weather condition, and precipitation probability (show it on the widget — designs included)
If this is a US customer, convert Celsius to Fahrenheit
If the user location doesn't match any city or API, return an error, do nothing, and do not show the weather widget

If you, as a PM, decide that supporting customers outside of the big cities is a priority, you can work with the API service provider and request support for latitude/longitude for the location parameter and create a small story for your tech team to update it when it is ready.

Similarly, if you really need wind speed support, you can either work with the same API or explore the Windy API to fetch just that. Having two underlying APIs serving the same customer feature is totally okay—in real applications, it easily can be 10 external APIs powering a small widget in the corner of the app screen (think of air quality, UV index, and so on).

Reverse example: exposing your own API

With our running app, we want to introduce a killer feature — routes for runners. Yes, Google can build a route for cars and walking, but running is slightly different. So you envision the user can specify the parameters of the jogging session and get a perfect route back. What you are asking from your development team is the following API:

# Input Parameters:
- Distance: how many kilometers a user wants to run today
- Time: the same but expressed in minutes
- Preference: parks, fields, urban, riverside, etc. - smth helping         
  algorithm to find the best match
- Circular or not: should a user come back to the starting point or not
# Output Parameters:
- Array of coordinates (lat, long): which can be plotted on the map
- Descriptions: ("turn left to John I street") for key segments
- Total distance: of the resulting route

# Potential errors
- Failed to build a route
- Input distance is too short/long
- Unknown preference passed

Notice that:

We don’t mention how this will be achieved — via fancy ML or some simple ruleset. But we state what users send and what we expect back — this is a good constraint to start with.
We moved from a fuzzy “route for runners” to a more concrete input/output contract. The tech team is already debating how to build it, where they see gaps in terms of requirements. For example, they can mention that they cannot support the preference parameter at all because map data doesn't specify details like “riverside” vs. “urban,” etc. So PMs can right away lower the bar of their dreams and remove this requirement.
Once the API is ready, you can offer it to your app team for integration and first testing. If successful, you can start selling it to sports businesses worldwide and charge a fee (for each 1000 API calls).

Summary

As a business leader, you should remember the following:

API consists of input and output (incl. potential errors).
You should focus on their main product value and use APIs to outsource work for the rest. You should be able to google the required functionality on the internet (most things are already built) and quickly understand the documentation.
If you need to set requirements for other PMs/teams, you can usually express them in the API’s input/output form. This also applies if you want to offer some of your functionality via API.