Platform Engineering · Lesson F23

HTTP: How Clients and Servers Talk

The client asks and the server answers. But in what words? They need a shared language, one both sides speak exactly the same way. That language is HTTP, the Hypertext Transfer Protocol. It is the language of the web, and it is simpler than its name sounds. This lesson reads one request and one response, line by line, in plain words.

Difficulty: Beginner · Know this first: F22 — Client and Server: Who Asks and Who Answers

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

Every hop charges rent in milliseconds. The bar below is a worked example for this lesson's scenarios, not a measurement from a live system. The shape is honest: the server's work is the biggest slice, and a missing page is cheap because there is no work to do. Step through the lesson or switch the scenario and watch the bar change.

Extra diagram · from scratch to master

One request, one response

Start with a client. Add one piece at a time until a full HTTP exchange is on the map, wrong turn included.

1 request, 1 response2 methods shown1 wrong turn
Client
asks the question
Request line
GET /index.html
Method
GET or POST
Headers
labels on it
Server
reads it all
Status 200
it worked
Body
the page itself
Status 404
no such page
Request / flowResponse · the way backFailure / dead end

Extra diagram · from scratch to master

Status codes: the server's short answer

Start with success. Add one family at a time until you can read any three-digit answer a server gives you.

5 families3 codes to know first1 server failure
200 OK
it worked
201 Created
it is made
301 Moved
go over there
400 Bad request
client mistake
Unauthorized
who are you
403 Forbidden
not for you
404 Not found
no such thing
Server error
we broke
Request / flowResponse · the way backFailure / dead end

Try it: change the inputs and watch it bend

Build a request and send it. Pick a method and a path, and the simulator shows the request line, the status code that comes back, and what it means. The paths and answers are a fixed teaching table, so every result is exact.

GET

The verb decides what the server does with the path. The same path means different things under different verbs.

/index.html

Six paths on one small teaching server. One is gone, one moved, and one user does not exist.

Try this: (1) GET /index.html. Request line GET /index.html HTTP/1.1, status 200 OK, the front page comes back. (2) POST /login. Status 200 OK, the login is accepted. (3) GET /missing-page. Status 404 Not Found. The server is fine, the page is not there. (4) DELETE /api/users/999. Status 404, because user 999 does not exist. (5) GET /old-page. Status 301, moved for good, follow the new address.

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Basic to master

I take the same idea four times here. First I learn what it is and why it exists. Then I learn to use it and read what it tells me. Then I design with it so one failure cannot take the system down. Last I run it for the world.

Basic — Reading one request and one response

Definition: An HTTP request is a request line, headers, an empty line, and sometimes a body. The request line is a method, a path, and a version. The response is a status line, headers, and a body. The status code is the verdict: 200 means it worked, 404 means the path does not exist, 500 means the server failed.

Types:

  • GET to ask for a thing.
  • POST to send data.
  • PUT, PATCH, and DELETE to store, change, and remove.

Uses: I use this every time a page misbehaves. I read the request line and the status code before I read anything else.

Dimensions: At low traffic one request and one response is the whole story. What breaks first is a wrong path, and I notice it as a 404. It costs nothing to learn the five methods and the three codes. It costs hours to debug a page without them. The trade is simple: HTTP is plain text and easy to read, and plain text is easy to get wrong by one character.

Intermediate — Headers, bodies, and status families

Definition: Headers are labels on the envelope: Host, Accept, Content-Type, Cookie. The body is the payload, described by the headers. Status codes come in families: 2xx success, 3xx redirection, 4xx client mistakes, 5xx server failures. A redirect is not an error. A 4xx is the client asking wrong. A 5xx is the server failing.

Types:

  • Request headers that describe the question.
  • Response headers that describe the answer.
  • Status families 2xx, 3xx, 4xx, 5xx.

Uses: I use curl at this level. I send a request by hand, read the status and the headers, and tell a client mistake apart from a server failure in one command.

Dimensions: As a service grows, the number of paths grows with it, and each one needs its method and its status decided on purpose. What breaks is a POST that should have been a GET, and I notice it when a browser refresh submits a form twice. It costs a rule: GET never changes anything, POST changes things. The trade is that the methods are few and the mistakes are many, so the rule earns its keep.

Advanced — Designing HTTP for a service

Definition: At this level I design the paths, the methods, and the status codes for a service, and I keep them consistent. The same kind of thing gets the same shape everywhere. Errors carry a message a human can act on, not just a code. Caching headers say what may be kept and for how long. Timeouts say how long the client waits.

Types:

  • Consistent paths across a whole service.
  • Errors with messages, not just codes.
  • Cache headers that say what may be stored.

Uses: I use this when I build or review an API. I read the paths like a menu and ask whether a stranger could order from it without a guide.

Dimensions: At ten times the traffic the headers are the load: cookies that grow, responses that are never cached, keep-alive connections that are never reused. What breaks is the response nobody cached, and I notice it in the traffic bill before the latency. It costs cache headers set on purpose and a habit of measuring response sizes. The trade is that a cacheable response is cheap to serve and slow to change, so I choose per path, not per service.

Read the status line. Every HTTP answer starts with a status code, and the code is the server telling you what happened. I read it with curl -I, which fetches only the headers. A 200 means it worked. A 404 means the thing is not there. The code is the first word of the answer.

$ curl -s -I https://example.com | head -5
HTTP/1.1 200 Connection Established

HTTP/1.1 200 OK
Date: Sat, 21 Nov 2026 00:12:34 GMT
Content-Type: text/html; charset=utf-8

Every flag in the commands above, letter by letter.

  • curl -I: -I sends a HEAD request. The server answers with headers only, no body. I use it to check a page exists without downloading it.
  • head -5: -5 keeps the first 5 lines. The response has two status lines here, because a proxy answers first, then the server.
  • One more flag worth knowing: curl --head is the long form of -I. Same request, spelled out. Long forms are for scripts a human will read later.

Check it: run curl -s -I https://example.com | head -5, then curl -s --head https://example.com | head -3. The outputs match.

Try it: run the command above, then run it for a page that does not exist, like https://example.com/nope. The first returns 200. The second returns 404. The server answered both times. The code is what differs.

404 is an answer, not a failure. A 404 means the server understood the request and the page is not there. That is useful information, not a broken connection. I treat 404 as a fact about the page, and 000 as a fact about the network. They point at different fixes.

$ curl -s -o /dev/null -w "%{http_code}\n" https://example.com/nope
404
$ curl -s -o /dev/null -w "%{http_code}\n" https://example.com
200

Every flag in the commands above, letter by letter.

  • curl -s -o /dev/null -w "%{http_code}\n": -s hides progress. -o /dev/null throws the body away. -w prints the status code. 404 means the page does not exist. 200 means it does.

Check it: run both commands above. One prints 404. One prints 200. The URL is the only difference.

Try it: run both commands. One page exists and one does not, and the server tells you so with the code. A 404 never means the server is down. It means the page is gone, and the fix is to check the address, not the server.

Master — HTTP for the world

Definition: At this level HTTP runs at scale: HTTP/2 and HTTP/3 with multiplexed streams, keep-alive connections reused across thousands of requests, edge caches serving most responses without ever reaching the origin, and status codes monitored per path with alerts on the 5xx rate. I know the difference between a 500 that pages me and a 404 that does not.

Types:

  • HTTP/2 and HTTP/3 with many streams on one connection.
  • Edge caches that answer before the origin is asked.
  • Per-path status monitoring with alerts on 5xx.

Uses: I use this when a service serves users on more than one continent, where every round trip costs and the edge is the product.

Dimensions: At a hundred times the traffic the protocol is still one request and one response. What changes is where the response comes from: the edge, the cache, or the origin, in that order. What breaks is the cache serving a stale answer as if it were fresh, and I notice it from users, not from dashboards. It costs cache rules reviewed like code and a way to purge fast. The trade is that the edge buys speed with staleness, and the budget for staleness is a business decision, not a technical default.

Redirects, and the loop they can make. A server can answer with a redirect, telling the client to ask somewhere else. One redirect is normal. A chain of redirects that never ends is a loop, and curl stops it with a limit. The limit is the safety net, and I set it on purpose.

$ curl -s -L --max-redirs 3 -o /dev/null -w "%{http_code} %{url_effective}\n" http://github.com
200 https://github.com/
$ curl -s -L --max-redirs 2 -o /dev/null -w "code %{http_code} redirects %{num_redirects}\n" https://httpbin.org/redirect/5
code 302 redirects 2

Every flag in the commands above, letter by letter.

  • curl -L: -L follows redirects. Without it, curl stops at the first 301 or 302 and prints that code. With it, curl follows the Location header to the next URL.
  • curl --max-redirs 3: --max-redirs 3 caps the chain at 3 redirects. The second command sets the cap to 2, and the chain has 5, so it stops at 2 with code 302. Without the cap, curl follows up to 50 redirects, then stops with an error.
  • curl -w "%{url_effective}\n" prints the URL the request ended on. %{num_redirects} prints how many redirects happened.

Check it: run curl -s -L --max-redirs 3 -o /dev/null -w "%{http_code} %{url_effective}\n" http://github.com. It prints 200 and https://github.com/. Then run the httpbin line with --max-redirs 2. It prints code 302 redirects 2.

Try it: run both commands. The first follows a redirect from http to https and lands on 200. The second hits a chain of five redirects, stops after two, and reports 302. Without the limit, curl would have followed all five. With a loop, it would have followed them forever.

Go deeper

Keep-alive is the first trade-off in HTTP. HTTP/1.1 reuses one TCP connection for many requests, which skips the handshake and the TLS setup for every request after the first. A server that closes the connection after each request pays the setup cost every time, and the page feels slow for a reason no log explains clearly.

The Host header is the reason one server can host many sites. The IP address gets the request to the machine. The Host header says which site on that machine you want. A request with the wrong Host header gets the wrong site's answer, or the default site, which is never the one you wanted.

A 301 and a 302 are not the same redirect. 301 means moved for good, and browsers remember it. 302 means moved for now, and browsers ask again next time. Using a 301 for a temporary move teaches browsers a lesson that is hard to unteach, because they cache the redirect.

Cookies are headers with memory. The server sends a Set-Cookie header, the browser stores it, and the browser sends it back on every later request to that site. That is how the server remembers you between requests that are otherwise independent. A cookie is small state, carried by the client, read by the server.

At 10x the traffic, the shape holds and the numbers grow. The request line stays one line. The server's work grows, and the response grows with it. I watch response sizes, because a page that grows by a megabyte costs every user on every load.

At 100x, the design changes. The edge answers most requests, the origin answers the rest, and the status codes are watched per path. A 5xx rate that climbs on one path is an incident, even when the site as a whole is green.

# ask for a page and see the whole conversation
curl -i https://example.com/index.html

# example response start (teaching example)
# HTTP/1.1 200 OK
# Content-Type: text/html
# Content-Length: 1256
#
# <html>...</html>

Every flag in the commands above, letter by letter.

  • curl -i: -i includes the response headers in the output of a normal GET request. The body follows the headers, after a blank line.
  • -i is not -I. -I sends a HEAD request and fetches no body. -i sends a GET request, fetches the body, and shows the headers too. I use -I to check a page. I use -i to see the whole conversation.

Check it: run curl -s -i https://example.com | head -6, then curl -s -I https://example.com | head -6. The first prints headers and then the body starts. The second prints headers only.

What the snippet means: curl sends a GET request and the -i flag shows the response headers as well as the body. The first line is the status line: HTTP/1.1 200 OK. The headers follow, saying the body is HTML and 1256 bytes long. The empty line ends the headers. Then the body begins. That is the whole conversation, and curl prints it in order.

Try it: headers first. Run curl -s -I https://example.com and read the first lines. The status line says 200. The content type says text/html. Those two lines tell you the request worked and what kind of thing came back, before a single byte of the page arrives.

$ curl -s -I https://example.com | head -5
HTTP/1.1 200 Connection Established

HTTP/1.1 200 OK
Date: Sat, 21 Nov 2026 00:12:34 GMT
Content-Type: text/html; charset=utf-8

One time it broke

What broke

A login page started failing for everyone at once. The form looked right. The server was up. Users typed the right password and got an error page that said nothing useful. The login had worked the day before, and nothing about the login had changed.

Timeline

  • 14:02,the first reports came in: login fails with a generic error.
  • 14:09,I opened the login page myself. The form loaded. I typed a test login and got the same error.
  • 14:15,I sent the same request with curl. The status code was 500. The server was failing while doing the work, not while reading the request.
  • 14:22,I checked the server logs. The login code called a user service that had been moved to a new address that morning, and the login code still had the old address.
  • 14:31,I updated the address and restarted the login service.
  • 14:38,I confirmed the login worked from three machines, not just mine.

What changed after

Three things. First, the login error page now shows a useful message and a code the support team can quote, instead of a blank error. Second, the login service health check now calls the user service, so a dead dependency fails the health check instead of waiting for a user to find it. Third, I wrote down the rule: read the status code first. A 500 means the server failed, and the server logs are the next stop. A 4xx would have meant the request was wrong, and I would have looked at the client instead. The code told me which side to debug, and it was right.

If you remember nothing else

Design exercise

Design the HTTP paths for a small library service. Users can list books, see one book, borrow a book, return a book, and search by title. The service must tell a client clearly when a book does not exist and when a book is already borrowed.

Clarifying questions to ask

  • Which method goes with each action, and why?
  • What status code comes back when a book does not exist?
  • What status code comes back when a book is already borrowed?
  • A client borrows the same book twice by accident. What should the second request return?
  • How does a client know the list of books is stale, and what header would help?

Rough sizing

Start with the count. Five actions, five paths, each with one method and one success code. A library with 10,000 books returns a list that is far too big for one response, so the list is paged: 20 books per page, with the page number in the path or the query. The search runs on the server, not the client, because sending 10,000 books to a phone so it can search them is a waste of everyone's bandwidth.

Trade-offs to name

GET for listing and reading buys safe repeats and costs nothing. POST for borrowing buys a clear creation and costs the risk of a double submit, so the borrow request carries an idempotency key. A 404 for a missing book buys clarity and costs nothing. A 409 Conflict for an already borrowed book buys a precise error and costs the client one more code to handle. And the list is cached for a minute, because a library's catalogue changes slowly and a stale list for sixty seconds harms no one.

Next in this series
Lesson F24 — APIs: Programs Talking to Programs