HTTP and APIs — the basics

What actually travels between a client and a server, and the small, standard vocabulary (methods, status codes, JSON) that almost every web API is built out of.

Beginner

4 min read

HTTP: the agreed-upon format for a request and response

HTTP (HyperText Transfer Protocol) is the standard format the web uses for client-server requests and responses — an agreed-upon shape so that any browser can talk to any server, and any HTTP client library can talk to any HTTP API, without every pair of programs needing their own custom communication format. Almost everything covered elsewhere in this domain — caching, load balancing, rate limiting — is ultimately about handling HTTP requests and responses well at scale.

The common HTTP methods, and what each one means

GET     /articles/5      — fetch article #5, don't change anything
POST    /articles        — create a new article
PUT     /articles/5      — replace article #5 entirely with new data
PATCH   /articles/5      — update part of article #5
DELETE  /articles/5      — delete article #5

The method (also called the verb) tells the server what kind of operation the client wants. This isn't arbitrary convention — GET is specifically expected to never change anything on the server (it's "safe" to call repeatedly, refresh a page as many times as you want), which is exactly why a browser can silently retry a failed GET but shouldn't silently retry a failed POST without asking first, since retrying POST could create a duplicate. Following this convention is what lets browsers, proxies, and caches all reason correctly about a request without knowing anything about what a specific API actually does.

Status codes: what the server is telling you about the response

200 OK                    — success
201 Created                — success, and something new was created
400 Bad Request            — the client sent something malformed
401 Unauthorized           — you need to log in
403 Forbidden              — you're logged in, but not allowed to do this
404 Not Found               — the thing requested doesn't exist
500 Internal Server Error   — something broke on the server's side

Status codes are grouped by their first digit: 2xx means success, 4xx means the client did something wrong (a bad request, missing auth), 5xx means the server itself failed. This grouping matters practically — client code can often handle "something in the 4xx range" or "something in the 5xx range" generically, without needing a special case for every individual code, while still checking for specific codes (like 404 or 401) when the exact reason matters.

An API: a defined way for programs to talk to each other

An API (Application Programming Interface) is a defined set of requests a program can make to another program, and what responses to expect back — the same idea as HTTP methods and status codes, but at the level of "what operations does this specific service support," not just "what does HTTP allow in general." A weather API might define GET /weather?city=London returning the current temperature; a payments API might define POST /charges to process a payment. Reading a new API's documentation is largely learning which URLs and methods it exposes, and what data it expects and returns for each one.

JSON: the format almost every modern API's data comes in

{
  "id": 5,
  "title": "Hello, API",
  "is_featured": true,
  "tags": ["intro", "basics"]
}

JSON (JavaScript Object Notation) is a lightweight, text-based format for structured data — objects ({}) with named fields, arrays ([]) of values, strings, numbers, booleans, and null. It's become the near-universal format for API request bodies and responses specifically because it's simple to read, simple to generate, and has a parser built into essentially every programming language — a Python program, a JavaScript frontend, and a mobile app can all read and write the exact same JSON without any of them needing to know what language the others are written in.

Putting it together: a real request

POST /api/articles HTTP/1.1
Host: example.com
Content-Type: application/json

{"title": "Hello, API", "body": "My first post"}

HTTP/1.1 201 Created
Content-Type: application/json

{"id": 5, "title": "Hello, API", "body": "My first post"}

This is the whole picture from the earlier lessons, combined: a client sends a request with a method (POST), a path (/api/articles), and a JSON body describing what to create; the server responds with a status code (201 Created) and a JSON body describing what was actually created, including the new id the server assigned. Every API interaction, no matter how complex the system behind it, is fundamentally built out of this same shape.