One API call
An API call is one request and one response, in text
A method and a path go out. A status code and a body come back.
Programs talk to services the way your browser does, with HTTP. Take one call apart. The request starts with a method, GET, and a path that names one server. Under it are headers: which host, who is asking, and what format to answer in. The response starts with a status code. Two hundred means it worked. Then its own headers, a blank line, and the body: the server you asked about, described in JSON.
curl · Going deeper
curl shows the whole exchange, and exits 0 even on an error status
In scripts, always pass --fail-with-body: otherwise a 401 looks like success.
REST
The URL names a thing; the method says what to do
GET reads, POST creates, PUT and PATCH change, DELETE removes.
Most APIs follow one convention, called REST. Things have addresses, and a few verbs act on them. GET reads: the whole collection, or one item. It changes nothing, so it is always safe to repeat. POST to the collection creates a new item. Send it twice and you get two. PUT replaces an item and PATCH changes part of one. DELETE removes it. Deleting twice leaves the same result as deleting once.
REST · Going deeper
Creating something: a request with a body
POST carries JSON in. 201 Created and a Location come back.
Status codes
The first digit of the status says whose move it is
2xx worked. 4xx fix your request. 5xx wait and retry.
Every response opens with a three digit code, and the first digit tells you what to do next. Two hundreds: it worked. Three hundreds: what you want is somewhere else, or has not changed. Four hundreds: the request is wrong. Bad input, no credentials, no permission, no such thing. Sending it again unchanged will fail again. Five hundreds: the server failed. Your request may have been fine, so wait a moment and retry.
Retries · Going deeper
Retry only what can succeed next time, and wait longer each attempt
Retry 429 and 5xx with exponential backoff and jitter. Do not retry other 4xx.
Authentication
A token proves who is calling; permissions say what for
Trade a secret for a short-lived token, and send the token with every call.
An API must know who is calling before it answers. The client first proves itself to an identity provider, with an id and a secret. It gets back an access token that is valid for a short time. That token goes in the Authorization header of every request to the API. The API checks the token, checks what this caller is allowed to do, and answers. No valid token is a four oh one. A valid token without permission is a four oh three.
JWT · Going deeper
A JWT is three Base64 parts: readable by anyone, signed, not encrypted
A JWT can be read by whoever holds it. Its signature only proves it was not altered.
Pagination
Long lists come in pages: follow "next" until it ends
Each page names the next. Stop when there is none.
Ask an API for everything, and it will not send everything. Here there are two hundred and fifty servers. The first request returns one hundred of them, and a cursor that marks where to continue. The second request passes that cursor, and gets the next hundred. The third gets the last fifty, and this time there is no next cursor. That is the signal to stop.
Pagination · Going deeper
Rate limits: 429 and Retry-After
429 means slow down. Wait for Retry-After, then try again.