The Reply — Responses

Lesson 4 · taught by Pip

You handed in your order slip. Now the waiter sets a plate in front of you. That plate is the response — the API's answer to your request. Every response has two parts worth knowing: the body (the goods you asked for) and the status code (a quick note on how it went). Let's take them one at a time.

The body: the goods

The body is the actual content — the weather, the directions, the list of coffee shops. It's the food on the plate.

Most APIs serve the body in a tidy format called JSON. The name looks technical, but the idea is plain: JSON is just a set of labeled pairs, like a filled-out form. Each line has a label on the left and its value on the right.

Here's a weather reply in JSON:

{
  "city": "Boston",
  "temperature": 54,
  "conditions": "cloudy"
}

Read it like a form someone filled in for you. City: Boston. Temperature: 54. Conditions: cloudy. The curly braces { } just mark where the form starts and ends. The labels always sit in quotes; the values are the answers (text gets quotes, plain numbers don't). That's the whole trick — you don't decode JSON so much as read it.

The status code: how it went

Before you even taste the food, the plate comes with a quick verdict: the status code. It's a three-digit number that tells you, at a glance, whether things went well — like a waiter saying "here you go" or "sorry, kitchen's out of that."

You don't need to memorize all of them. You just need to know the three families, sorted by their first digit.

200s — success. The order went through. The most common is 200, which simply means "OK, here are the goods." When you see a 200, the body is the real answer and you can trust it.

400s — your mistake. The number starts with 4 when the request was wrong. Maybe you misspelled the address, left out a required note, or asked for something that doesn't exist. The famous 404 ("not found") lives here — it means "there's nothing at that address." A 400-family code is the kitchen saying, politely, "we can't make this with the slip you gave us." The fix is on your side: check your request.

500s — the service's fault. The number starts with 5 when the kitchen itself broke — something went wrong on the API's end, not yours. Your order may have been perfect; their stove just caught fire. There's usually nothing to fix on your side except wait and try again later.

So the first digit tells you almost everything: 2 = it worked, 4 = check yourself, 5 = check them. 🔦

Putting it together

A full response, then, is the plate plus the verdict. You glance at the status code first to know whether to trust the plate, then you read the body to get what you came for. A 200 with a clean JSON body is the happy ending of every API call.

Your turn

Take the weather JSON above and read it aloud as a form: label, then value, line by line. Then picture three things going wrong on a request for a city that doesn't exist — a typo in your address, a missing required note, the API's own server crashing. Sort each into the 400 family or the 500 family, and say why in one sentence each.

Next we'll meet the doorman: Keys — Who Gets In, and why some kitchens won't cook for a stranger.