One API call

An API call is one request and one response, in text

Requestwhat the client sendsGET /v1/servers/web-01 HTTP/1.1Host: api.example.comAuthorization: Bearer eyJhbGciOi...Accept: application/jsonmethod and path: what to do, and to which resourceheader: which serverheader: who is asking, proved by a tokenheader: the format wanted backResponsewhat the server answersHTTP/1.1 200 OKContent-Type: application/json{"name": "web-01", "state": "running"}status code: what happenedheader: the format of the bodybody: the resource itself, as JSONAn API call is one request and one response, and both are plain text.Every console click, CLI command and line of SDK code ends as a message like this one, sent overHTTPS. An API is the published list of requests that a service will accept.

A method and a path go out. A status code and a body come back.

curl · Going deeper

curl shows the whole exchange, and exits 0 even on an error status

curl 8.5 against a small example API on this machine$ curl -i -H "Authorization: Bearer $TOKEN" $API/v1/servers/web-01HTTP/1.1 200 OKServer: BaseHTTP/0.6 Python/3.13.18Date: Mon, 16 Nov 2026 08:28:11 GMTContent-Type: application/jsonContent-Length: 38{"name": "web-01", "state": "running"}$ curl -s $API/v1/servers/web-01; echo " exit=$?"{"error": "missing or invalid token"} exit=0$ curl -sS --fail-with-body $API/v1/servers/web-01; echo " exit=$?"curl: (22) The requested URL returned error: 401{"error": "missing or invalid token"} exit=22OptionDoes-iprint the response headers-Hadd a request header-X POSTchoose the method-dsend a body (implies POST)-s -Ssilent, but keep errors--fail-with-bodynon-zero exit on 4xx, 5xx-o filesave the body to a filecurl exits 0 on a 401 or a 500 unless you pass --fail or --fail-with-body.A script that pipes the result onward then treats an error message as data. In scripts use curl -sS --fail-with-body,and read JSON with jq: curl ... | jq -r .state prints running. -v also shows the request headers, token included.

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

MethodPathDoesChanges dataSafe to send twiceGET/serverslist every serverno✓yesGET/servers/web-01read oneno✓yesPOST/serverscreate a new oneyes✗no: it creates anotherPUT/servers/web-01replace ityes✓yesPATCH/servers/web-01change part of ityesusuallyDELETE/servers/web-01remove ityes✓yesThe URL names a thing. The method says what to do with it.REST is this convention: resources have addresses, and a small fixed set of verbs acts on them./servers is a collection and /servers/web-01 is one item in it. A request that is safe to send twiceis called idempotent: after a timeout you can simply retry it. POST is not, so a retry may duplicate.

GET reads, POST creates, PUT and PATCH change, DELETE removes.

REST · Going deeper

Creating something: a request with a body

RequestPOST /v1/servers HTTP/1.1Content-Type: application/json{"name": "web-03", "size": "small"}ResponseHTTP/1.1 201 CreatedLocation: /v1/servers/web-03{"name": "web-03", "state": "starting"}To create a resource, the request carries its description in the body.201 Created confirms it, and the Location header gives the address of the new resource. Content-Typetells the server how to read the body. To filter a list, add query parameters to the URL instead:GET /v1/servers?state=running&limit=50.

POST carries JSON in. 201 Created and a Location come back.

Status codes

The first digit of the status says whose move it is

2xxit worked200OK201Created204No ContentCarry on.3xxlook elsewhere301Moved Permanently304Not ModifiedFollow the new address.4xxthe request is wrong400Bad Request401Unauthorized403Forbidden404Not Found429Too Many RequestsFix the request first.5xxthe server failed500Internal Server Error502Bad Gateway503Service UnavailableWait, then retry.The first digit of the status code says whose move it is.Programs branch on the code, never on the message text. A 4xx will repeat until the request changes,with one exception: 429 means slow down and try later. A 5xx is not your fault and often passes, soretry it after a pause. A script that ignores the code will read an error page as data.

2xx worked. 4xx fix your request. 5xx wait and retry.

Retries · Going deeper

Retry only what can succeed next time, and wait longer each attempt

StatusRetry?400, 404, 409, 422no: the same request fails again401once, after fetching a new token403no: a permission has to change408, 429yes: after Retry-After, if given500, 502, 503, 504yes: after a pauseno answer (timeout)yes, if the method is idempotentWait before each retry: 1 s, doubling (drawn to scale)retry 11 sretry 22 sretry 34 sretry 48 sretry 516 s5 retries wait 31 s in all. With jitter, each wait is arandom time up to the length of its bar.Retry what may pass on its own: 429 and 5xx. Fix what will not: the other 4xx. And wait longer each time.Jitter matters: a thousand clients that failed together and all retry after exactly 1, 2 and 4 seconds arrive togetheragain. Set a ceiling on the wait and on the attempts, then fail loudly. A retried POST can create a duplicate, so APIsthat move money accept an Idempotency-Key header: the same key sent twice returns the first result, not a second charge.

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

Clienta script or serviceIdentity providerissues tokensAPIchecks every requestclient id and secretan access token, valid for 1 hourGET /v1/servers + Authorization: Bearer token200 OK, and the data✗401 Unauthorized: no valid token. Get a new one.✗403 Forbidden: a valid token, but not allowed.A token proves who is calling. Permissions decide what the caller may do.An API key is a long-lived password for a program: simple, and dangerous when it leaks. A token isissued for a short time and a limited scope. Keep both out of code and out of Git: read them froman environment variable or a secret store.

Trade a secret for a short-lived token, and send the token with every call.

JWT · Going deeper

A JWT is three Base64 parts: readable by anyone, signed, not encrypted

The token after "Authorization: Bearer": 184 characters, three parts joined by dots (HS256, signed with an example key)eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZXBsb3ktYm90Iiwic2NvcGUiOiJzZXJ2ZXJzOnJlYWQiLCJpYXQiOjE3NzMwNjQ4MDAsImV4cCI6MTc3MzA2ODQwMH0.kRbcnxB5vLCYoRA6eS0iyMPiwCAwOBWlyODDQC5DiWQHeaderhow it is signed{"alg":"HS256","typ":"JWT"}Payloadthe claims{"sub":"deploy-bot","scope":"servers:read","iat":1773064800,"exp":1773068400}Signaturethe proofHMAC-SHA256( header + "." + payload, key )for deploy-bot, to read servers; issued 14:00 and expires 15:00 UTC on 2026-03-09 (seconds since 1970)only a holder of the key can produce it; change one character above and it no longer matchesA JWT is signed, not encrypted: anyone holding it can read it, and nobody without the key can alter it.The first two parts are plain JSON in Base64. The API checks the signature and exp on every request, with no callto the identity provider. So never put a secret in the payload, and keep lifetimes short: a stolen token works untilexp. Real providers mostly sign with a private key (RS256, ES256), so an API needs only the public key to verify.

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

RequestItems returnedThe response also saysGET /v1/servers?limit=100100next: "c2"GET /v1/servers?limit=100&cursor=c2100next: "c3"GET /v1/servers?limit=100&cursor=c350next: null, so stop250 items, in 3 requestsA long list comes back one page at a time.The server caps each response to protect itself and you. Every page says where the next one starts,as a cursor or a page number, and the last page has none. A script that reads only the first responsesilently works on part of the data. Most SDKs offer a paginator that follows the links for you.

Each page names the next. Stop when there is none.

Pagination · Going deeper

Rate limits: 429 and Retry-After

HTTP/1.1 429 Too Many RequestsRetry-After: 30X-RateLimit-Limit: 5000X-RateLimit-Remaining: 0you are calling too fastwait 30 seconds, then try againyour budget: 5,000 requests an hourand none of it is leftAn API limits how fast each caller may go.When the budget is spent it answers 429. Honour Retry-After; where there is none, back offexponentially, doubling the wait each time. Hammering a rate-limited API only lengthens the block.Ask for only what you need, cache what does not change, and spread scheduled jobs out.

429 means slow down. Wait for Retry-After, then try again.

Lesson complete

You finished “APIs”

Nicely done.

Open in a new tab