In Part 1, an API was the waiter: it takes your order to a kitchen you never see and brings back the answer. This part looks at the order itself (the request) and what comes back (the response). It's the part of APIs that turns up most in user stories, acceptance criteria and bug reports.
One request, one response
Every API conversation is a round trip. The client (an app, a web page, another server) sends a request. The server sends back a response. Then the conversation is over, and the next question starts a new one.
One request, one response
The weather page, in a visitor's browser
GET /v1/forecast?latitude=51.80&longitude=-0.21200 OK { "temperature_2m": 11.6, "weather_code": 2 }Open-Meteo's weather API
LikePosting an order form and getting a delivery note back. You fill in the form the way the shop asks, and the note always comes back in the same layout, so you know where to look.
A request is a web address
Most web APIs are asked questions with a web address, just like the ones you type into a browser. Here's a shortened version of the one the weather page sends for Welwyn Garden City, split into its parts:
A request is a web address
https://api.open-meteo.comWhereThe restaurant's address /v1VersionWhich edition of the menu /forecastEndpointThe dish, or the counter you queue at ?latitude=51.80&longitude=-0.21ParametersYour order details, like "no onions" ¤t=temperature_2mFieldsWhat you want on the plate? starts the question. Each parameter is a name and a value joined by =, and & separates them. Change the numbers and you get the weather somewhere else.Try it: build a request and send it
Pick a place and what you'd like back. The address updates as you go, and the button sends it to the real weather API.
Change the place in the builder and watch which part of the address changes. That's all a different place is to an API: different numbers in the order.
The version number is worth a second look. When a provider wants to change its answers in a way that would break existing products, it publishes a v2 alongside v1 and gives everyone time to move. "They're retiring v1 in March" is a sentence that should end up on a roadmap.
Four verbs cover most of it
A request also says what kind of thing you want to do. These are called methods, and four of them cover nearly everything:
Four verbs cover most of it
Read something
Read the menu
Show today's forecast, a product's stock level, an order's status. The weather page only ever uses GET.
Create something
Place a new order
Send a contact form, place an order, take a payment.
Change something
Swap the chips for salad
Update a delivery address, change a quantity in the basket.
Remove something
Cancel the order
Remove a saved card, delete an account.
The response is JSON
The answer usually comes back as JSON (JavaScript Object Notation). Don't let the name put you off. It's plain text, laid out as labels and values.
JSON is a labelled delivery note
On paperA delivery note: every value has a label next to it
- Time zone
- Europe/London
- Time
- 14:15, 4 Nov 2026
- Temperature
- 11.6°C
- Weather code
- 2
In JSONThe same note, written so code can read it
{
"timezone": "Europe/London",
"current": {
"time": "2026-11-04T14:15",
"temperature_2m": 11.6,
"weather_code": 2
}
}The weather API sends back more than this: units, the next five days and a few other details. The weather page's "Behind the scenes" section shows the whole answer, live.
Status codes are the waiter's reply
Every response comes with a three-digit status code that says how it went, before you even look at the data. Pick one to see what the customer should see, and what the team should do:
Status codes are the waiter's reply
200 OK
The waiter says"Here you go."
The customer sees: The weather, as normal.
The team should: Nothing. This is the happy path.
401 Not allowed
The waiter says"Members only, sorry."
The customer sees: A short "weather unavailable" note. Never a technical error, and never a sign-in box: it's not their key.
The team should: Get alerted straight away: the key is missing, wrong or expired. Customers can't fix this.
404 Not found
The waiter says"That's not on the menu."
The customer sees: The same "weather unavailable" note.
The team should: Check the address. Often an old API version has been switched off, so watch for retirement dates.
429 Too many requests
The waiter says"One order at a time, please."
The customer sees: A moment's wait, then the weather. The page tries once more after a pause.
The team should: Cache answers and slow down. If it keeps happening, the plan's limits are too low for your traffic.
500 Server error
The waiter says"There's a problem in the kitchen."
The customer sees: A friendly "didn't load" message and a Try again button.
The team should: Nothing to fix your side. Check their status page, and decide how long to show the message before hiding the feature.
No reply No reply
The waiter says"Nobody comes to the table."
The customer sees: A loading state, then the same friendly message after the wait (10 seconds on the weather page).
The team should: Agree how long is too long, then treat it like a 500.
What this means for product managers
- Read the menu early. API documentation lists every endpoint, parameter and field. Before a story goes into a sprint, check the data you need is actually there, in the shape you need it.
- Write acceptance criteria for the unhappy paths. "Given the API returns a 500 or doesn't answer within 10 seconds, the customer sees a friendly message and a retry button" is a perfectly good criterion, and it saves a lot of "what should happen here?" later.
- Watch the versions. Note the version you build against, and put retirement dates on the roadmap.
- Be careful with POST. Anything that creates or charges should be safe if the customer taps twice or the connection drops mid-request. Ask the team how that's handled.
Part 3 follows the answer to the screen: how the page turns this JSON into the words, numbers and icons you see.