How to read API documentation: a guide for product managers

Product job specs keep asking for the same thing in different words: "comfortable working with APIs", "technical", "experience with third-party integrations". Nobody expects a product manager to write the integration. What they want is someone who can open a provider's documentation, work out what the API can do for the product, what it would take, and what could go wrong, then have a useful conversation with engineers about it.

The first five parts of this series explained how APIs work, using a weather API I chose. This part is about someone else's API, and the skill that sits on top of everything else: reading the docs. The example is a page many product people will meet sooner or later, Stripe's Create a refund. Stripe's docs are widely copied, so if you can read this page, you can read most of them. When you're done, there's a quick challenge to try it out.

What the job spec really means

All five come down to the same skill. You don't need to memorise anything. You need a way of reading that turns a page of technical reference into product decisions, and that's what the rest of this part is.

Seven questions for any API docs

API documentation isn't meant to be read from top to bottom, like a book. It's a reference, more like a dictionary. I read it with seven questions in mind, roughly in this order, and stop when I have what I need:

The first two take a couple of minutes and tell you whether the API is even worth a closer look. The last two are where the hidden work lives, and they're the ones most often skipped.

A docs page, part by part

Most API reference pages share a layout: a sidebar of everything the API offers on the left, the explanation and parameters in the middle, and example code on the right. Here's a simplified copy of Stripe's Create a refund page. Pick a number to see what each part is and what to read it for.

curl https://api.stripe.com/v1/refunds \
  -u "sk_test_DEMO-KEY-0000-NOT-REAL:" \
  -d payment_intent=pi_DEMO123 \
  -d amount=1250 \
  -d reason=requested_by_customer \
  -d "metadata[order_id]"=A1042

{
  "id": "re_DEMO123",
  "object": "refund",
  "amount": 1250,
  "currency": "gbp",
  "payment_intent": "pi_DEMO123",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "created": 1793923200,
  "metadata": { "order_id": "A1042" }
}

Questions 1 and 2: the nouns and the verbs

The sidebar is the fastest way to see what an API can do. The nouns (Charges, Customers, Disputes, Refunds) are the things it knows about. Open one and the verbs underneath are what you can do to them. Here's the whole Refunds section, translated into things a product could do:

This is the step that answers "what could this API do for us?", and it's worth writing down even when the answer seems obvious. Five endpoints became six possible features, from a refund button for the support team to a report for finance. It also shows the limits: you can only update a refund's metadata, so a refund sent for the wrong amount can't be edited, only followed by another refund.

Question 3: what must I send?

Parameters are the details of the order. For each one, I look for four things:

• Is it required? Usually a label next to the name. But read the descriptions too: Create a refund marks neither payment_intent nor charge as required, because you have to send one or the other.
• What type is it? A string (text), an integer (whole number), a boolean (true or false), an enum (a fixed list) or an object (a group of values).
• What are the units? "Smallest currency unit" means pence, so 1250 is £12.50. Dates are often seconds since 1 January 1970, not a date you'd recognise.
• What happens if I leave it out? Leave out amount and the whole amount left on the payment is refunded. Defaults are decisions someone else made for you.

The question behind all four is: does our product already know this? Stripe needs the ID of the original payment. If your order system doesn't save it, that's work to add to the estimate before anyone writes a line of refund code.

Question 4: what comes back?

The example response shows the object you get back. Three things in it matter most to a product manager: the ID (your product saves it to find the refund again), any field a person will see, and the status.

Statuses are where the design work hides. The docs list five for a refund, and "refunded" is only one of them:

If someone says "it's just one API call", the status list is the polite way to show it isn't. Each row is a message to write, a state to design or an alert to set up.

Question 5: what can go wrong?

Every docs site has an errors page listing its status codes (Part 2) and what an error message looks like. Then each endpoint adds its own: Create a refund fails if the payment has already been fully refunded, or if you ask for more than is left.

I turn each one into a sentence for the ticket: "If the agent enters more than the amount left, show 'You can refund up to £X' and don't send the request." Catching it in your own product first is kinder to the customer than passing on the API's error.

Question 6: what happens later?

A refund isn't over when the API answers. It can sit at pending for days, then succeed, or fail because the card was cancelled. Nobody is asking the API at that moment, so the API tells you instead, through webhooks (Part 1). Stripe calls these events, and the ones for refunds include refund.created, refund.updated and refund.failed.

This is the most commonly missed part of an integration. If nobody listens for refund.failed, the customer is told their money is on its way, and it never arrives. Look for the events section of any docs, and for each event ask: who needs to know, and what do we do?

Question 7: what are the rules?

Around the endpoints sit pages that apply to every call. They're easy to skip and expensive to miss:

Then there's what the docs don't say. Pricing, support and uptime promises are usually on the provider's main website or in your contract, and Part 4 has a checklist of questions to ask before you integrate.

From docs to a user story

Here's how the reading turns into a ticket. Almost every line of the acceptance criteria comes from something on the docs page.

As a customer service agent, I want to refund one item from an order, so that the customer gets their money back without me refunding the whole order.

• The amount starts at the item's price and can't be more than the amount left to refund. If it is, the agent sees "You can refund up to £X" and nothing is sent. (Parameters: amount, and the description's rules.)
• The agent must pick a reason: duplicate, fraudulent or requested by customer. Fraudulent asks for confirmation, because it also blocks the card. (The reason enum.)
• The order number and support ticket number are saved with the refund. (Metadata.)
• The order page shows the refund's status and updates when Stripe reports a change. If a refund fails, the agent's team is alerted and the customer is told how they'll be refunded instead. (Statuses and events.)
• Clicking Refund twice creates one refund, not two. (Idempotency.)
• Tested end to end in Stripe's test mode before release. (Test keys.)

Engineers will add detail, but a ticket like this starts the conversation in the right place, and that's what "comfortable with APIs" looks like in practice.

Talking about it in an interview

"Tell me about a time you worked with an API" is a common interview question for product roles. A good answer shows how you think, not how much code you know. I'd structure it like this:

1. The goal: what the product needed, in customer terms.
2. What I read: the docs, and what they told me the API could and couldn't do.
3. What I found: the hidden work, such as a status nobody had designed for, an ID we weren't saving or a rate limit we'd hit at peak.
4. What I decided: how it shaped the scope, the tickets or the plan.
5. What happened: the outcome, and what I'd check earlier next time.

If you haven't worked on an integration yet, read one docs site properly (the list below is a good start) and talk through what you'd build with it, using the seven questions. Being able to say "I read Stripe's refund docs and the thing I'd flag first is the failed status" is a stronger answer than most.

Test yourself

Pick a question to see my answer.

Practise on real docs

The quickest way to practise is the API docs challenge: six product requests, such as "refund one item when all I have is the customer's email", and a page of Stripe's real endpoints. You pick the endpoints each one needs, then see the calls in order, what each returns and the outcome. It takes about ten minutes.

After that, try a whole docs site. These are all public and free to read:

• Open-Meteo: the weather API from this series. No key, and you can try requests right on the page.
• Stripe API reference: payments. Try the seven questions on Customers or Disputes.
• GitHub REST API: issues, pull requests and more. A good one for pagination and rate limits.
• Twilio Messaging: sending texts. Look for the statuses a message goes through, and the webhooks that report them.

Pick one, give yourself twenty minutes and write down one line for each of the seven questions. That page of notes is most of what an engineer would want from you at the start of an integration.

Words you'll see in docs

That's the end of the series. If you've read all six parts, you know what an API is, how a request and response work, how an answer becomes a page, how keys and limits work, what a real integration looks like, and how to read the docs for the next one. For the other kind of API you'll meet in docs, carry on with GraphQL for product managers.