Stop 08 · Technical Fluency for PMsTopics · 1/11

How APIs Work

In short

Almost every feature you spec talks to an API: payments, maps, login, your own backend. If you can read a request and a response, half of engineering chat suddenly makes sense.

An API is a contract that lets two pieces of software exchange data in a predictable format — understanding requests, responses and endpoints lets you scope integrations without guessing.

The purple blob as a waiter carries an order slip and a tray between a table and a kitchen hatch.

Think of it like this

The restaurant waiter

You don't walk into the kitchen. You tell the waiter "one masala dosa, less oil", he takes it in, and brings back the dosa or says it's finished. The menu is the contract: what you can ask for and how. That's an API.

Watch it happen

The app asks for one order

App

Orders API

Database

GET /orders/42

1/5The app sends a request: method GET, path /orders/42, plus a token proving who the user is.

The big ideas

What you need to know

Endpoint + method

The path says what (/orders/42), the method says the action: GET reads, POST creates, PATCH updates, DELETE removes.

JSON is the usual format

Most web APIs send data as JSON: named fields with values, easy for both people and code to read.

Status codes

2xx means success, 4xx means the request was wrong (404 not found), 5xx means the server failed.

Auth

Most APIs need a token or key, so they know who's asking and what they're allowed to do.

See it in code

Walk through the code

json

1{2  "id": 42,3  "status": "out_for_delivery",4  "items": [5    { "name": "Masala dosa", "qty": 2 },6    { "name": "Filter coffee", "qty": 1 }7  ],8  "total_inr": 260,9  "eta_minutes": 1210}

1/3Simple fields: the order's id and its current status as a fixed text value.

A sample JSON response for GET /orders/42. Reading responses like this helps you spot missing data early.

Save yourself the pain

Common mistakes

Oops

Assuming any data you see in the app is "easy to get" for a new screen.

Do this instead

Ask which API returns it. It might need a new endpoint or a slow extra call.

Oops

Ignoring error cases in your spec.

Do this instead

Ask what the screen shows on 404, 500 or a timeout, and write it down.

Your mission

Call a real API

~20 min

Quick check

The app gets a 404 from GET /orders/999. What most likely happened?

Go deeper

1Use a tool like Postman to send a request to a free public API and inspect the response.
2Learn to read simple API documentation and identify required vs optional fields.
3Practice explaining an API integration to a non-technical stakeholder in one sentence.