HTTP and APIs

Ask, and be answered

The web runs on a single, stubbornly simple shape: one side asks, the other answers. HTTP (HyperText Transfer Protocol) is the request/response protocol behind nearly every web page and most APIs. A client sends a request naming what it wants, and a server sends back exactly one response — either the thing that was asked for or a reason it cannot be had, like ordering at a counter: you state what you want, and you get back either the thing or a reason you cannot have it. The client always speaks first; the server only ever replies.

That asymmetry is the whole frame. The request and the response are ordinary messages travelling over a TCP connection — HTTP is the layered agreement about what those messages say, not about how the bytes cross the wire, and when the connection is encrypted it runs over port 443. Everything else in this concept is detail hung on that one exchange: what a request is made of, what the three-digit answer means, and how programs use the same exchange to talk to each other.

The model on this page steps through a few exchanges one message at a time — a read that succeeds, a read that fails, and a write that creates something. Each packet, endpoint, and state badge can be clicked to explain itself.

What a request is made of

An HTTP request is not free-form; it has a fixed shape with four parts in a fixed order. First comes the request line: a method (the verb, such as GET), a path that names the resource (a URL like /orders/42), and the protocol version. After the request line comes a set of headers, each a label carrying metadata about the request. Then a single blank line marks the end of the metadata. Finally, an optional body carries the payload — the data being sent, present on a POST but usually absent on a plain GET.

The response the server sends back mirrors that shape. In place of the request line it opens with a status line — the protocol version, a status code, and a short reason phrase — then its own headers, then a blank line, then the body that actually carries the answer. Learn the one layout and you can read both halves of every exchange: the metadata lives up top in the line and the headers, and the content, if any, lives below the blank line.

The verbs of the web

The method is the verb of a request — the part that says what to do with the resource the path names. Four carry most of the traffic. GET reads a resource. POST submits data, typically to create something new. PUT replaces a resource with the representation you supply. DELETE removes one. The path says which noun; the method says which action.

Two properties sort these verbs, and both matter the moment something goes wrong. A method is safe if it only reads and changes nothing on the server; a method is idempotent if making the same call many times leaves the server in the same state as making it once. GET is both safe and idempotent — reading a resource twice is no different from reading it once. POST is neither: post the same order twice and you may create two orders. PUT and DELETE are idempotent but not safe — they change the server, but repeating a replace or a delete lands on the same end state.

That distinction is why a browser will happily retry a GET after a hiccup but warns before resending a POST. The verb is a promise about what the request does, and knowing the promise tells you when a retry is harmless and when it is not.

The three-digit answer

Every response opens with a three-digit status code, and the first digit tells you almost everything by sorting the code into one of five classes. A 1xx code is informational; a 2xx code means the request succeeded; a 3xx code is a redirect, pointing the client somewhere else; a 4xx code is a client error, meaning the request itself was wrong; and a 5xx code is a server error, meaning the request was fine but the server failed to handle it. Read the first digit and you already know whether things went well and, if not, roughly whose fault it was.

A handful of landmark codes are worth knowing by name. 200 is OK — the request succeeded and, for a GET, the resource is in the body. 301 is Moved Permanently — the resource's URL has changed and the new one is in the response. 404 is Not Found — the server cannot find the requested resource. 500 is Internal Server Error — the generic signal that the server hit a situation it did not know how to handle. The class tells you the category; the exact code tells you the specifics.

The labels on the envelope

Headers are the labels on the envelope: name-and-value lines that carry metadata about a message, kept separate from the body they describe. They appear on both requests and responses, and they are how each side tells the other how to interpret what follows without the recipient having to guess.

A few come up constantly. Content-Type names the media type of the body — for a JSON payload it reads application/json — so the recipient knows whether it is holding text, an image, or structured data. Content-Length gives the size of the body in bytes, so the recipient knows exactly how much to read. Authorization carries credentials that identify the client to the server, which is how a request proves it is allowed to touch a protected resource.

The point of pulling this out of the body is that metadata and content can be handled independently. A caching proxy can read the headers to decide what to do without ever parsing the payload, and a server can reject a request on its Authorization header before it spends any effort on the body at all.

Each request stands alone

HTTP is stateless: there is no link between two requests, and the server keeps no memory of a client from one request to the next. Each request arrives as a self-contained message the server reads fresh and then forgets, like a letter the reader opens fresh and then sets aside, remembering nothing unless the letter itself names who sent it. Nothing about the last request lingers to shape the next one.

That sounds like it would make logging in impossible, and on its own it would. Continuity — a session, the sense that the server knows who you are across many requests — has to be carried in each request rather than remembered by the server. The usual mechanism is a token the client includes every time: a cookie the browser stores and resends, or a credential a program attaches to each call. The server reads that token, recognizes the client, and still remembers nothing once the response is sent.

Statelessness is a deliberate trade. It costs every request a little extra baggage, and it buys enormous freedom: because any request stands entirely on its own, any one of a hundred identical servers can handle it, and none of them needs to know what the others are doing.

Programs talking to programs

An API is just the same HTTP exchange with a program on the asking end instead of a browser. The style most services follow, REST, maps cleanly onto the parts you already know: a resource is addressed by a URL, the action on it is an HTTP method, and the data that moves is carried as a payload, conventionally JSON with a Content-Type of application/json. Pair a verb with a noun — get this thing, create this thing, delete this thing, like pairing an action with a thing: get this thing, create this thing, delete this thing — and you have described most of what an API does.

Because it is the same protocol, a program calls a service exactly the way a browser fetches a page: a GET to read a resource, a POST to create one, and a status code back to say how it went. Scripts, mobile apps, and AI agents all reach services this same way, which is why one service can serve a browser and a program from the same endpoint without knowing or caring which is calling.

That uniformity has a sharp edge worth naming: every endpoint you expose is reachable by anyone who can address its URL, so every exposed endpoint is also attack surface. The same door that lets a legitimate program in is the door an attacker probes.

Reading the exchange when it breaks

Almost everything you will build that touches a network speaks HTTP. Serving a site is answering HTTP requests; calling an API is sending them; and the programs and AI agents that stitch services together are doing nothing more exotic than the same request and response in a loop. Learn to read the exchange once and you can read it everywhere it shows up.

The single most useful habit is reading the status code first, because it tells you at a glance whose problem you are looking at. A 4xx says the request was wrong — a bad path, a missing Authorization header, a 404 for something that is not there — so the fix is on the caller's side. A 5xx says the request was fine but the server failed, so the fix is on the server's side. That one digit routes you to the right half of the system before you have read a single log line.

The same skill turns a broken integration from a mystery into a diagnosis. When a program's call fails, the response is already telling you what went wrong and where to look; the difference between guessing and knowing is just whether you read the answer the exchange handed you.