APIs for Product Managers
Anatomy of a Request and a Response
Five things happen every time software talks to an API. Know all five and you can read almost any spec.
Here is a real, minimal example — a request to get information about a customer, and the response that comes back.
Fig 1.1 — The request / response cycle
REQUEST
GET https://api.example.com/v1/customers/8842
Headers:
Authorization: Bearer sk_live_9x7...
Accept: application/json
RESPONSE
Status: 200 OK
Body:
{
"id": "8842",
"name": "Acme Logistics",
"plan": "enterprise",
"created_at": "2024-03-11T09:00:00Z"
}
Break that into its five parts, because these five parts are the vocabulary of the entire course.
Part | What it is | Plain-English translation |
|---|---|---|
Endpoint | https://api.example.com/v1/customers/8842 | "The specific address you're asking, like a URL for a webpage, but for data instead of a page" |
Method | GET | "The verb — what kind of action this is: read, create, update, delete" |
Headers | Authorization, Accept | "Metadata about the request — who's asking, and what format they want back" |
Status code | 200 OK | "One number that tells you, before you even read the body, whether it worked" |
Body | The JSON object | "The actual data, structured as nested key-value pairs" |
You will see the term JSON constantly — it stands for JavaScript Object Notation, but you never need to know that etymology. All you need is the shape: curly braces hold an object, each line is a "key": value pair, and values can be text, numbers, true/false, lists, or nested objects. If you can read that customer example above and tell me the customer's plan is "enterprise," you can already read 80% of the API specs you'll encounter in your career.
YOUR MOVE THIS WEEK
Find any public API's documentation (Stripe's and GitHub's are famously well-written and free to browse). Find one example request and response. Without asking an engineer, identify the endpoint, the method, one header, the status code, and three fields in the body. If you can do that in under five minutes, this lesson has already paid for the course.