How software works · Guide for product managers

APIs for product managers

Almost every feature you ship moves data through an API. This guide explains what actually happens when your app "calls the API", what engineers mean when they talk about endpoints and 401s, and how to write better API requirements — or supervise an AI agent that builds them.

Guide 2 of 10 in the technical PM path

12 min read · Updated 25 September 2026 · By the TechPMer team

Why a PM should care

APIs are where your product's promises become contracts. When a mobile app, a partner, a payment provider or your own frontend needs data, it asks through an API. That means APIs decide:

• What is possible. If the API does not return a field, the screen cannot show it.
• What is fast or slow. One screen that needs five API calls will feel slower than one that needs one.
• What breaks. Most "the page is empty" bugs are an API call that failed quietly.
• What partners can build. A public API is a product in its own right, with users, docs and breaking changes.

You do not need to write an API. You need to read one, reason about it and ask the right questions.

What an API is — in one picture

API stands for Application Programming Interface: a defined way for one piece of software to ask another for something.

A useful analogy is a restaurant. You (the frontend) do not walk into the kitchen (the backend and database). You order from a menu (the API documentation) through a waiter (the HTTP request), and you get a plate back (the response). The menu limits what you can order — and that is the point: the kitchen can change its recipes without customers noticing.

In a typical web app the flow is:

Browser (frontend)  →  HTTP request  →  Server (backend)  →  Database
Browser (frontend)  ←  HTTP response ←  Server (backend)  ←  Database

Requests and responses

Every API call is a request and a response. A request has:

• A method — what you want to do (see the table below).
• A URL (endpoint) — what you want to do it to, for example /api/projects/42.
• Headers — metadata, most importantly who you are (the auth token).
• A body (optional) — the data you are sending, usually JSON.

Here is a real-looking example: creating a task.

POST /api/projects/42/tasks
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{ "title": "Write release notes", "dueDate": "2026-10-01" }

And the response:

HTTP/1.1 201 Created
Content-Type: application/json

{ "id": "t_981", "title": "Write release notes", "dueDate": "2026-10-01", "status": "open" }

That { ... } format is JSON (JavaScript Object Notation): named fields with values. If you can read a spreadsheet row, you can read JSON.

HTTP methods (the verbs)

This is a common convention (REST), not a law of physics. Some APIs use POST for everything, and GraphQL APIs usually send every request as a POST to a single endpoint. Ask which style your team uses.

Status codes: how to read a failure

The response always carries a three-digit status code. The first digit tells you who to talk to.

Rule of thumb: 4xx means the request was wrong (client side), 5xx means the server failed. Knowing this alone makes bug reports dramatically better.

Authentication, API keys and secrets

Most APIs need to know who is calling (authentication) and what they may do (authorization).

• User tokens (often JWTs or session cookies) identify a signed-in person. They expire, which is why users get logged out.
• API keys identify an application — for example your server calling OpenAI or Stripe. They are secrets, like a password for your whole company account.

The single most important rule: secret API keys must live on the server, never in frontend code. Anything shipped to the browser can be read by anyone who opens developer tools. When an engineer says "we can't call that API directly from the client, it would expose the key", this is what they mean — the request has to go through your own backend.

Rate limits, pagination and timeouts

Three non-functional details that turn into product behaviour:

• Rate limits cap how many requests you can make (for example 100 per minute). Bulk imports, sync features and AI features hit them first.
• Pagination returns large lists in pages (for example 50 items at a time). "Show all 20,000 orders on one screen" is an API design question, not only a UI one.
• Timeouts decide how long to wait. A third-party call that sometimes takes 30 seconds needs a loading state, a retry plan and maybe a background job.

Webhooks: when the API calls you

Normally your app asks another service for data. A webhook reverses that: the other service calls your URL when something happens — "payment succeeded", "subscription cancelled", "file processed".

Webhooks matter for PMs because they create timing and failure cases: the event can arrive late, twice or not at all. Good implementations verify the webhook signature (so nobody can fake a "payment succeeded"), handle duplicates safely, and have a fallback check.

REST vs GraphQL (briefly)

REST exposes many endpoints, one per resource (/users, /orders/7). GraphQL exposes one endpoint where the client asks for exactly the fields it needs. GraphQL can reduce over-fetching for complex screens; REST is simpler to cache and reason about. Neither is "modern" or "legacy" — it is a trade-off, and most teams should stay with what they already run well.

What engineers may tell you

• "That endpoint doesn't return the field — we'd need a backend change." The screen needs data the API does not expose yet; it is more work than a UI tweak.
• "It's a breaking change, we need to version the API." Existing clients (for example old mobile app versions) would break if the response shape changed.
• "We're getting 429s from the provider." You hit a third-party rate limit; the fix may be caching, batching or a paid tier.
• "The webhook isn't idempotent." Processing the same event twice would do the thing twice (for example grant access twice or send two emails).
• "It's a CORS error." The browser blocked a call to another domain; usually a server configuration fix.

Questions a good technical PM asks

1. What does the request and response look like for this feature? Can I see an example?
2. What happens on each failure — 401, 403, 404, 429, 500 — and what does the user see?
3. Is any secret or API key involved? Where does it live?
4. Are there rate limits or costs per call on the third-party side?
5. Will this change break existing clients or integrations?
6. How do we know it works in production — logs, alerts, dashboards?

Red flags

• An API key or "secret" appears in frontend code, a screenshot or a public repository.
• The only error handling is a generic "Something went wrong".
• A "payment succeeded" webhook is trusted without verifying its signature.
• A list endpoint returns everything with no pagination "because we only have 200 items today".
• Nobody can say which status code the API returns for "not allowed".

Using an AI coding agent with APIs

AI agents such as Claude Code and Codex are good at API wiring, and also good at confidently wiring it insecurely. When you ask one to integrate an API, give it:

• The official documentation link and the exact endpoints you need.
• Where the call must run: "call it from a server function; the API key must only be read from an environment variable on the server."
• The failure cases and the UI you expect for each.
• The acceptance criteria, for example "when the provider returns 429, show 'Too many requests, try again in a minute' and do not retry more than twice."

Then review what it built: search the frontend code for the key name, trigger a failure on purpose, and check the network tab in your browser's developer tools to see the real requests and status codes.

Try it yourself

Open any website you use at work, press F12, choose the Network tab and reload the page. Click a request marked fetch or xhr and look at its method, URL, status code and response. Ten minutes of this is the fastest way to make APIs feel concrete. Then paste a response into our free JSON explainer, look up its status in the HTTP status codes tool, and rebuild the request in the API request builder.

In the TechPMer course you go further: week 6 (“APIs & the Backend”) covers APIs and integrations inside your own project, with prompts for your AI agent and a checklist for reviewing what it produced.