HTTP as the Foundation of Most APIs
🌐 HTTP as the Foundation of Most APIs
What HTTP Actually Is
HTTP (HyperText Transfer Protocol) was originally built for fetching web pages, but the same request/response mechanics — a method, a target, some headers, an optional body, and a status code back — turned out to be a perfectly good general-purpose way for any client and server to exchange structured data, not just HTML pages. That reuse is why it became the default transport for web APIs rather than something purpose-built.
HTTP Methods (Verbs)
Every HTTP request declares a method — a verb describing the kind of action being requested. The protocol itself doesn't enforce what each verb "means"; it's a widely followed convention that well-designed APIs stick to.
| Method | Conventional Meaning | Has a Body? | Idempotent? |
|---|---|---|---|
| GET | Retrieve data, no side effects | No | Yes |
| POST | Create something new, or trigger an action | Yes | No |
| PUT | Replace a resource entirely with what's sent | Yes | Yes |
| PATCH | Partially update a resource | Yes | No (usually) |
| DELETE | Remove a resource | Usually not | Yes |
Idempotent means: calling it once has the same end result as calling it five times in a row. GETting the same resource repeatedly doesn't change anything, and PUTting the exact same replacement data five times leaves the resource in the same final state as doing it once. POST is the odd one out — posting "create a new order" five times typically creates five separate orders, which is exactly why it's not idempotent. This distinction matters more than it might seem — Chapter 4 covers why idempotency is something real API design has to deliberately account for, especially when a client might retry a request after a dropped connection.
Anatomy of a Request
A Real GET Request
A Real POST Request (With a Body)
Every request has three parts: a method + path (what's being asked for, and how), a set of headers (metadata about the request), and — for methods like POST/PUT/PATCH — an optional body carrying the actual data being sent.
Status Codes: How the Server Reports Back
Every response starts with a three-digit status code, grouped into five classes by its first digit:
| Range | Class | Common Examples |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirection | 301 Moved Permanently, 304 Not Modified |
| 4xx | Client Error — you did something wrong | 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests |
| 5xx | Server Error — it did something wrong | 500 Internal Server Error, 503 Service Unavailable |
The single most useful habit for reading an unfamiliar API's behavior is checking which class a status code falls into before worrying about the exact number — a 4xx means "fix your request," a 5xx means "the problem is on their end, maybe retry later."
Headers: Metadata Riding Alongside the Data
Headers are key-value pairs that travel with a request or response but sit outside the body — metadata about the exchange, rather than the actual content. Content-Type tells the receiving side how to parse the body (e.g. application/json), Authorization carries credentials, and Accept tells the server what response format the client can handle. If you want to see real headers in action, the Web Developer Tools course's Network panel chapter (wdt_lesson_04) shows exactly how to inspect every header on a live request in your browser — and the HTTPS/TLS course covers how headers like Authorization stay protected in transit via encryption.
Headers vs. Body — Different Jobs
Headers
Metadata: content type, auth token, caching rules, what formats are acceptable. Small, always present in some form.
Body
The actual payload: the JSON, XML, or file being sent or returned. Optional — many requests (like a plain GET) have none at all.
Putting It Together: A Full Exchange
Chapter 1's Weather Example, Made Concrete
💻 Coding Challenges
Challenge 1: Classify HTTP Methods
Match each action to the HTTP method that best fits it: (a) fetch a user's profile, (b) create a new order, (c) update just the email field of an existing user, (d) delete a comment, (e) replace an entire user record with new data.
Goal: Practice mapping real actions onto the conventional meaning of each verb, including the PUT/PATCH distinction.
Challenge 2: Read a Status Code
For each of these status codes — 201, 404, 429, 500 — explain in plain language what it tells the client, and what the client should probably do next in each case.
Goal: Practice treating status codes as actionable information, not just numbers to memorize.
Challenge 3: Spot the Missing Header
A client sends a POST request with a JSON body but no Content-Type header at all. Explain why this can cause problems on the server side, and what header should be added and set to what value.
Goal: Practice recognizing that headers aren't optional decoration — servers often depend on them to correctly parse the body.
A very common real-world mistake: an API documents an endpoint as PUT /users/42 for "updating a user," but the implementation only expects the fields being changed — not the full record. Genuine PUT semantics mean the entire resource is replaced with whatever's sent; if a client sends only { "email": "new@example.com" } to a true PUT endpoint, a strictly correct server would wipe out every other field not included. Many APIs quietly use PUT to mean "partial update" anyway, which works until a client follows the spec literally and something else gets accidentally erased. If partial updates are the real intent, use PATCH — that's exactly what it's for.
🎯 What's Next
With HTTP's building blocks in place, the next chapter goes deeper into REST APIs In Depth — the architectural constraints (statelessness, uniform interface, HATEOAS) and resource-modeling philosophy that turn plain HTTP into a coherent, well-designed API style.