HTTP is the conversation every API has: your program sends a request, the server sends back a response. Both share the same three-part shape — a start line, headers, and an optional body. Learn that shape once and you can read and debug any API call, in any tool.
The request has three parts
- Start line — the method + the path + the HTTP version: GET /v1/orders HTTP/1.1.
- Headers — metadata about the request (who you are, what you are sending).
- Body — the payload, only for methods that send data (POST, PUT, PATCH).
The methods (verbs)
The method states your intent. The server decides what actually happens, but the conventions are near-universal:
| Method | Intent | Body? | Repeat-safe? |
|---|---|---|---|
| GET | Read data. The most common by far. | No | Yes — never changes data |
| POST | Create something, or trigger an action. | Yes | No — sending twice creates two |
| PUT | Replace a resource entirely. | Yes | Yes — same result if repeated |
| PATCH | Update part of a resource. | Yes | Usually |
| DELETE | Remove a resource. | Sometimes | Yes |
| HEAD / OPTIONS | Metadata / capability checks — headers only, no body. | No | Yes |
"Repeat-safe" (idempotent) means doing it again has the same effect as doing it once — which matters when a network retry might resend a request. A retried GET or PUT is safe; a retried POST can double-charge or create a duplicate.
The response and its status code
The server answers with a status line (a three-digit code), its own headers, and usually a body (the JSON you want). The first digit of the code tells you what happened:
| Range | Meaning | Common ones |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirect — go somewhere else | 301 Moved, 302 Found, 304 Not Modified |
| 4xx | You made a mistake | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests |
| 5xx | The server failed | 500 Internal Error, 502 Bad Gateway, 503 Unavailable, 504 Timeout |
Tip · The 4xx vs 5xx split is the first thing to check when something fails: 4xx means fix your request (wrong key, bad URL, missing field); 5xx means the server is unhappy — back off and retry.
Content-Type and MIME types
A MIME type (or "media type") names the format of a body so the receiver knows how to read it. It travels in the Content-Type header, and the same values describe both what you send and what you get back.
| MIME type | What it is |
|---|---|
| application/json | JSON — the default for almost every modern API. |
| application/xml, text/xml | XML data. |
| application/x-www-form-urlencoded | Form fields as a=1&b=2, like an HTML form. |
| multipart/form-data | File uploads and mixed form fields. |
| text/plain, text/html | Plain text, or an HTML page. |
| application/octet-stream | Raw bytes — a generic file download. |
Two headers work together: Content-Type describes the body you are sending; Accept tells the server which format you would like back. Set Content-Type wrong and the server may reject or misread your body.
Headers worth knowing for automation
Headers are key: value metadata lines. A handful come up constantly when you build integrations — these are the ones to memorise.
| Header | Direction | Why it matters |
|---|---|---|
| Authorization | request | Carries your credentials — Bearer <token> or Basic <...>. The #1 header in API work. |
| Content-Type | both | The format of the body being sent. |
| Accept | request | The format you want back, e.g. application/json. |
| User-Agent | request | Identifies your client. Some APIs reject requests that do not send one. |
| Content-Length | both | Size of the body in bytes. |
| Location | response | Where a 3xx redirect — or a 201 Created — points to. |
| Retry-After | response | On a 429/503, how many seconds to wait before retrying. Respect it. |
| Cache-Control / ETag | response | Whether and how you may cache; ETag enables cheap "has it changed?" checks. |
| X-RateLimit-Remaining | response | How many requests you have left in the window — watch it to avoid 429s. |
| Set-Cookie | response | Session cookies; relevant for login-based sites, less so for token APIs. |
Tip · When an automation "works in the browser but not in my tool", the difference is almost always headers — a missing Authorization, the wrong Content-Type, or an absent User-Agent/Accept. Log the exact request headers and compare the two.
These are universal HTTP concepts: they work the same whether you call the API from a browser, a script, a no-code tool, or an AI agent. Every later lesson is just these fundamentals applied.