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.
An API is the waiter
In a restaurantYou, the customer, decide what you want
An app or web page that needs something it can't do itself
In a restaurantThe waiter takes your order to the kitchen
A fixed set of questions another company lets you ask, and the rules for asking
In a restaurantThe kitchen cooks it. You never go in there
The other company's servers, data and know-how
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.
REST: the kind of API in this series
The weather page, and most of the APIs you'll come across, use a style called REST (short for Representational State Transfer, which nobody says out loud). When an engineer calls an API "RESTful", they mean it follows a few simple conventions:
- Every thing has its own web address. A forecast, a product, an order: each is a "resource" with an address like
/forecastor/orders/1234. - Standard verbs say what you're doing. GET to read, POST to create, PUT or PATCH to change, DELETE to remove. Part 2 covers them.
- Each request stands on its own. The server doesn't remember the last question, so every request carries everything needed to answer it.
- Answers usually come back as JSON, the labelled text you'll meet in Part 2.
In the restaurant, REST is a set menu with numbered dishes. You order "number 12" and it arrives the way the kitchen always plates it. That's simple and predictable, and it's why REST is the default on the web. But it isn't the only kind of API.
Other kinds of API
Other kinds of API
An address for each thing
A set menu with numbered dishes
Web addresses plus GET, POST and friends, answered in JSON. The most common kind on the web, and the one this series uses.
One address, ask for exactly what you want
Writing your own order on one slip
The product lists the fields it needs and gets just those back, in one trip. Shopify and GitHub offer one. It has a series of its own.
Strict, formal and older
Filling in an official form in triplicate
Messages in XML with a rigid contract. You'll still meet it in banking, insurance, government and older enterprise systems.
Fast talk between servers
Kitchen staff calling orders in shorthand
Compact messages that people can't read but machines handle very quickly. Mostly used between a company's own services, rarely by web pages.
They call you
The restaurant texting you when your table's ready
The other system sends a message to your address when something happens, such as a payment clearing. More on these below.
A line kept open
Staying on the phone instead of ringing back
Both sides can send at any moment, for chat, live scores, shared documents and multiplayer games.
REST, GraphQL or webhooks?
The alternative you'll hear about most is GraphQL. Instead of a set menu, the product writes its own order: one address, and a list of exactly the fields it wants. Webhooks often come up in the same conversation, though they work the other way round: the other system tells you when something happens (there's more on them below). None of the three is better in general, and each has trade-offs a product manager should know about:
REST, GraphQL and webhooks: the pros and cons
Pros
- Simple and familiar. Almost every developer and tool knows it, and you can try a GET in a browser's address bar.
- Easy to cache. Each address is its own answer, so browsers and networks can keep copies and save repeat trips.
- Clear when it fails. Status codes say how it went, and monitoring tools understand them out of the box.
- Predictable costs. Each address does a known amount of work, so limits and pricing per request are easy to reason about.
Cons
- Too much or too little. Fixed answers mean over-fetching, and screens that need related data make several trips.
- New screens wait for new endpoints. If no address returns what a design needs, the back-end team has to build one.
- Versions to manage. Breaking changes mean a
v2and a migration for everyone.
Pros
- Exactly what the screen needs. One request, only the fields asked for, which helps most on phones and slow connections.
- Front-end teams move faster. A new screen can often be built by writing a new query, with no back-end change.
- A typed schema. One menu of everything on offer, checked automatically, so typos and missing fields show up before release.
- Changes without versions. New fields can be added freely, and old ones marked as deprecated and retired once nobody asks for them.
Cons
- More to set up and learn. A schema, a server and new tooling, which is a lot for a small, simple API.
- Harder to cache. Every request goes to one address, usually as a POST, so the easy, address-based caching doesn't apply.
- Errors hide in 200s. Failures come back inside the answer, so monitoring and alerting need extra work.
- Expensive questions. One deeply nested query can ask for a huge amount of data, so servers need limits on how much a query may cost.
Pros
- Instant. You hear the moment something happens, not the next time you think to ask.
- No wasted asking. Nothing is sent when nothing has changed, which saves requests, rate limits and money.
- Made for events in someone else's system. A payment clearing, a parcel delivered, a form submitted, a subscription cancelled.
Cons
- Something has to be listening. You need a server that's always on to receive them. A static site like this one can't.
- Messages go missing or arrive twice. If your server is down, providers retry, so the same event can turn up more than once, or out of order.
- Anyone could knock. The address is open to the internet, so every message needs checking against the provider's signature.
- Harder to test. You wait for the other side to call you, and many only send the bare news, so you still call their API for the details.
If your team is weighing up GraphQL, or already uses it, GraphQL for product managers is a three-part follow-on to this series, with a live demo of its own. The rest of this series sticks with REST.
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:
APIs you already rely on
The shop sends the card details to a payments provider's API, which answers "approved" or "declined".
The page asks a maps API for the map tiles around an address.
The order page asks the courier's API where the parcel is now.
The site asks Google's API to confirm who you are, without ever seeing your password.
A product page pulls its star rating and reviews from a reviews platform's API.
The weather demo asks Open-Meteo's API for the forecast. Part 5 takes it apart.
If you work on an online shop, APIs, webhooks and GraphQL in ecommerce walks through an order stage by stage, with the platforms that typically handle each step.
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.
Asking versus being told
LikeRinging the restaurant every few minutes to ask if your table is ready
An API call. Your product asks whenever it wants an answer, and gets one even when nothing has changed.
- 9:00Your product asks courier"Has the parcel arrived?""Not yet"
- 9:05Your product asks courier"Has the parcel arrived?""Not yet"
- 9:10Your product asks courier"Has the parcel arrived?""Yes, at 9:08"
3 requests and the customer hears 2 minutes late
LikeLeaving your number, so the restaurant texts you when your table is ready
A webhook. Once, your product gives the courier an address to call. Then the courier tells you the moment something happens.
- OnceYour product tells courier"Tell me at this address when it arrives""Will do"
- 9:08Courier tells your product"The parcel was delivered at 9:08"Customer told straight away
1 message the moment it happened
Phrases you'll hear, translated
- "It's a REST API." It has an address for each thing and answers in JSON. The most common kind.
- "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.