HTTP Fundamentals

Anatomy of an exchange

GET /api/users/42 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <token>

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"id": 42, "name": "Ada"}

A request has a method, a path (with an optional query string such as ?page=2), headers and an optional body. A response has a status code, headers and an optional body. HTTP is stateless: each request stands alone, and things like logins are carried by cookies or tokens in headers.

Methods

Method	Typical meaning
GET	Read a resource. Should not change anything.
POST	Create something or trigger an action.
PUT	Replace a resource.
PATCH	Change part of a resource.
DELETE	Remove a resource.

GET, PUT and DELETE are meant to be idempotent: repeating them gives the same result. POST is not, so retrying it can create duplicates.

Status codes

Range	Meaning	Examples
2xx	Success	200 OK, 201 Created, 204 No Content
3xx	Redirect	301 Moved Permanently, 302 Found, 304 Not Modified
4xx	Client error	400 Bad Request, 401, 403, 404, 429 Too Many Requests
5xx	Server error	500 Internal Server Error, 502, 503, 504

Four codes are often confused:

• 401 Unauthorized means you are not authenticated (missing or invalid credentials). Check first: is the credential sent (an Authorization header or cookie), and is it valid and not expired?
• 403 Forbidden means the server knows who you are, but you may not do this. Check first: the permissions or role of that identity. Sending the credential again will not help. See Authentication vs Authorization.
• 404 Not Found means there is no such resource at that URL. Check first: the URL, the method, the base path and the environment (right server, right version). Some APIs also use 404 to hide resources you may not see.
• 500 Internal Server Error means the server failed unexpectedly. The fault is not in your request, so look at the server logs for the error behind it.

In short, 4xx means the caller should change something, 5xx means the server has to be fixed.

Common headers

Content-Type (format of the body), Accept (formats the client wants), Authorization (credentials), Cache-Control (caching rules), Location (redirect target), Set-Cookie and Cookie. Never log or share the contents of Authorization.

Inspecting traffic

Open the browser developer tools (F12), choose the Network tab, reload and click a request to see its headers, payload, timing and response. For command-line and GUI tools see API Testing Tools. Request and response bodies are usually JSON, and HTTPS wraps all of this in encryption; see TLS and HTTPS Basics.

Try it

Open any website with the Network tab visible. Find one request that returned 200 and one that returned 304 or a redirect, and read their headers. Then request a URL that does not exist on the same site and note the status code.