What is an API? A plain-English guide for product managers

If you work in product, you'll hear about APIs every week. "We'll pull that from the API." "The payments API is down." "That's a third-party integration, so it depends on their roadmap." You don't need to write code to be good at your job, but knowing what's going on behind those sentences helps you scope work, ask sharper questions and spot risks before they become incidents.

This series explains APIs the way I'd explain them to a colleague at a whiteboard: with diagrams and everyday comparisons, and with one real example running all the way through. That example is a small live weather page on this site, which asks a free weather API for the forecast and turns the answer into icons.

The short version

API stands for Application Programming Interface. It's a way for one piece of software to ask another piece of software for something, following an agreed set of rules. Your product asks a question, the other system answers, and neither needs to know how the other works inside.

The restaurant comparison

The classic way to picture it is a restaurant. You don't walk into the kitchen and cook your own dinner. You read the menu, tell the waiter what you'd like, and the waiter brings it back.

The comparison holds up surprisingly well:

• The menu is the documentation. It lists what you can ask for and how to ask for it. If it's not on the menu, you can't order it.
• The waiter is the API. It takes a request in an agreed format and brings back an answer in an agreed format.
• The kitchen is the other company's system. It can change its ovens, its staff and its suppliers, and as long as the menu stays the same, your dinner arrives as normal.

That last point is the real value. An API lets two teams, or two companies, work independently. The weather service can rebuild its forecasting models and the weather page keeps working, because the questions and answers haven't changed.

APIs you already rely on

Most products are stitched together from APIs, many of them from other companies. Here are some you'll have used this week:

Why product managers should care

APIs turn up in nearly every product decision, even when nobody uses the word:

• Build or buy. Using a payments, maps or search API can save months. The trade-off is that a key part of your product now lives on someone else's roadmap.
• Dependencies and risk. If their API goes down, so does that part of your product. What should the customer see when that happens?
• Cost. Many APIs charge per request. A feature that's cheap with a thousand users can be expensive with a million.
• Timelines. "The API doesn't return that field" is a common reason for a story to stall. Reading the docs early saves surprises in the sprint.
• Data and privacy. Every request sends data somewhere. Does it include personal details, and is that covered by your privacy policy?

Asking versus being told

There's one more idea worth knowing early, because it comes up in planning: the difference between calling an API and receiving a webhook.

Phrases you'll hear, translated

• "We'll integrate with their API." Our product will send requests to their system and use the answers.
• "Is there an endpoint for that?" Is this question on their menu?
• "The API is rate limited." We're only allowed so many requests a minute. More in Part 4.
• "It's a third-party dependency." Someone else runs it, so we can't fix it if it breaks.
• "We need an API key." We have to sign up and identify ourselves on every request. Also Part 4.

Next, Part 2 looks at what a request and a response actually look like, using the weather page's real request.