{"canonical_url":"https://engineer.company/glossary/http/","content_markdown":"# HTTP\n\n## What it is\n\nHTTP, the Hypertext Transfer Protocol, is the set of rules a browser, an app or\na script follows to ask a server for something and receive a reply, and when\nthat conversation runs inside an encrypted TLS connection the same protocol\ngoes by HTTPS. Every exchange has two halves. The client sends a request: a\nmethod such as `GET` or `POST`, the target it wants, a list of header fields\nand sometimes a body. The server answers with a three-digit status code, header\nfields of its own and, usually, a body. Loading a page, fetching an image and\none program calling another are all the same exchange repeated.\n\n```http\nGET /pricing/ HTTP/1.1\nHost: example.com\nAccept: text/html\n\nHTTP/1.1 200 OK\nContent-Type: text/html; charset=utf-8\nCache-Control: max-age=600\n```\n\nThe specification calls it stateless. Each request has to carry everything the\nserver needs in order to understand it, and the protocol keeps no memory from\none exchange to the next. Logins, baskets and sessions are built on top,\nusually with cookies: a header field the server sets once and the client sends\nback on every later request.\n\nThe vocabulary is small and precise. `GET` and `HEAD` are safe, meaning they\nask for a representation and are expected to change nothing. `PUT` and\n`DELETE` are idempotent: sending the same one twice leaves the server where\nsending it once would have. `POST` promises neither. Status codes are grouped\nby their first digit, 2xx for success, 3xx for redirection, 4xx for a problem\nwith the request and 5xx for a problem on the server, so a client meeting an\nunfamiliar code still knows roughly what happened.\n\nThat meaning has stayed put while the wire format has been replaced twice.\nHTTP/1.1 writes messages as lines of text over a TCP connection, and each\nconnection returns its responses one at a time, in order. HTTP/2 keeps the\nsame methods and fields but frames them in binary and interleaves many\nrequests on one connection. HTTP/3 carries the same semantics over QUIC, a\ntransport built on UDP, which avoids TCP’s transport-level head-of-line\nblocking across independent streams. Since 2022 the IETF has published the semantics in one document and each\nversion's wire format in another, which is why \"what does 404 mean\" and \"how\nare the bytes laid out\" now have separate answers.\n\nHTTP versus HTTPS is therefore no contest between two protocols: HTTPS is HTTP\nwith TLS underneath, which encrypts the exchange and proves the server's name.\nWebSocket starts life as an HTTP request and then upgrades the connection into\na two-way channel, and gRPC is a convention for calling remote functions that\nruns over HTTP/2.\n\n## Why it matters\n\nNearly every system that talks to another over the internet already speaks\nHTTP, so the decision that matters is rarely whether to use it. It is whether\nto use what it defines or to treat it as a pipe and rebuild the rest on top.\n\nUsing it fully pays off because a long chain of software already reads the\nvocabulary. A client library may retry a `GET` that timed out; it must leave a\n`POST` alone, and so must any proxy in between. A cache can keep a response\nmarked `max-age=600` for ten minutes and serve it to the next reader without\nasking the server. Monitoring counts 5xx answers as errors without being told\nto. An API that sends every call as a `POST` to one address and reports\nfailure inside a 200 response gives all of that up, and every client then has\nto learn that API's private rules.\n\nThe model has edges. Request and answer suit a client that knows what it\nwants; they suit a server with news to push far less, which is why live\nupdates usually travel over WebSocket, server-sent events or polling.\n\nPlain HTTP on the public internet is a different question with a short answer.\nBrowsers label it as insecure, anyone on the path can read and alter it, and\ncertificates cost nothing, so public traffic belongs on HTTPS. The choice\nbetween HTTP/1.1, HTTP/2 and HTTP/3 is mostly a setting on the server or the\nedge in front of it, and application code stays the same because the meaning\nof every request is the same.\n\n## What it looks like in practice\n\nThe clearest case on this site is an API that was moved onto a framework built\naround HTTP's own shape.\n[The HTTP API moved from Fiber to Huma v2](/portfolio/migrated-the-api-to-huma-v2-at-100-parity/),\nwhich runs on top of Fiber, so each endpoint is declared with input and output\nstructs and the validation comes from the types rather than from checks written\nby hand. An OpenAPI description falls out of the same declarations, and a CI\ncheck compares the routes the server registers against the ones the\ndescription advertises. At 649 paths and 760 operations parity is 100%, held\nthere because a route nobody described fails the build. Exactly two endpoints\nstayed on raw Fiber: the WebSocket ones, where Huma's request-and-response model\ndoes not fit.\n\nThe site itself uses content negotiation. Every page is published as HTML and\nas Markdown, and one way to get the Markdown is to send\n[a request with `Accept: text/markdown` and let the server choose](/cli/). The\nonion address on that page is plain `http://` on purpose. Because that address\nencodes the service's public key, Tor has already authenticated and encrypted\nthe circuit by the time the first HTTP request travels over it.\n\nHTTP also turns up as a tool in infrastructure code. When a second server was\nprovisioned,\n[both providers' firewalls were written directly against their REST APIs](/portfolio/provisioned-a-second-server-from-code/)\nthrough a generic HTTP task instead of a vendor collection. That removed a\ndependency and its version drift, at the cost of writing each request shape by\nhand. It has a further cost the page names: the generic HTTP task declares no\ncheck-mode support, so a dry run of the play that creates the machine skips\nevery task in it, and the rehearsal is run against the firewall play instead.\n\n## Where it goes wrong\n\nMost HTTP bugs come from using a word in the vocabulary to mean something other\nthan what the rest of the chain hears.\n\n### An error that arrives as a success\n\nAn API answers 200 and puts `\"error\": \"card declined\"` in the body. Caches may\nstore it, dashboards count it as a success, and retry logic in the client never\nfires. Send the status code that fits, 4xx or 5xx, and describe the problem in\nthe body; RFC 9457 defines a JSON shape for that, served as\n`application/problem+json`.\n\n### A link that deletes things\n\nA `GET` request changes state, for example an unsubscribe or delete link in an\nemail. Crawlers, link previews in chat apps, security scanners and browser\nprefetching all follow links on their own, and each of them can trigger it.\nAnything that changes data belongs behind `POST`, `PUT` or `DELETE`, with a\nconfirmation page if the link must exist.\n\n### A payment taken twice\n\nThe client sends a `POST`, the connection drops before the answer arrives, and\nthe client tries again. The server had already processed the first one. HTTP\ngives the client no way to tell those cases apart, so the API has to: accept an\nidempotency key in a header and return the stored result for a repeated key, or\nlet the client choose the new resource's identifier and create it with `PUT`.\n\n### A form that turns into a GET\n\nA server answers a `POST` with 301 or 302 to send it elsewhere. For historical\nreasons the specification lets user agents switch the method to `GET` on those\ntwo codes, and many do, so the body is dropped on the way. When the method has\nto survive the redirect, use 307 or 308.\n\n### The wrong variant from a cache\n\nOne URL serves HTML or Markdown, English or Danish, depending on request header\nfields. A cache that has been told nothing stores whichever variant it saw\nfirst and hands it to the next reader. The response has to name the fields it\ndepends on, for example `Vary: Accept`, so that a cache keeps one copy per\nvariant instead of one per URL.\n\n## Further reading\n\n- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — methods,\n  status codes and header fields, defined once for every version.\n- [RFC 9111: HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111) — when a\n  stored response may be reused and what `Cache-Control` tells a cache.\n- [RFC 9112: HTTP/1.1](https://www.rfc-editor.org/rfc/rfc9112) — the text wire\n  format, connection handling and message framing.\n- [RFC 9113: HTTP/2](https://www.rfc-editor.org/rfc/rfc9113) — binary frames\n  and many streams over one connection.\n- [RFC 9114: HTTP/3](https://www.rfc-editor.org/rfc/rfc9114) — the same\n  semantics mapped onto QUIC streams.\n- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457)\n  — a standard JSON body for describing what went wrong.\n\n\u003chttps://engineer.company/glossary/http/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How HTTP requests and responses work, why methods and status codes carry meaning, how HTTP/2 and HTTP/3 differ, and five mistakes APIs repeat.","formats":{"gemtext":"https://engineer.company/glossary/http/index.gmi","gopher":"https://engineer.company/glossary/http/gophermap","html":"https://engineer.company/glossary/http/","json":"https://engineer.company/glossary/http/index.json","markdown":"https://engineer.company/glossary/http/index.md","pdf":"https://engineer.company/glossary/http/index.pdf"},"kind":"page","language":"en","title":"What is HTTP?","url":"https://engineer.company/glossary/http/","version":1}