What REST actually means
REST stands for Representational State Transfer. Roy Fielding defined it in his 2000 doctoral dissertation at the University of California, Irvine, as an architectural style, not a product or a file format. An API is called RESTful when it follows these constraints.
- Client-server: interface and storage are separate and change on their own.
- Stateless: each request carries everything needed. The server does not remember your last joke.
- Cacheable: responses say whether they may be reused.
- Uniform interface: resources have URLs and a small, fixed set of methods.
- Layered system: proxies and CDNs can sit in between unnoticed.
- Code on demand (optional): the server may send JavaScript to run.
In practice, "REST API" usually means: nouns in the URL (/orders/42), verbs in the HTTP method, and the outcome in the status code. Get those right and clients understand your API before reading the docs.
HTTP methods: the verbs
RFC 9110, the HTTP Semantics standard the IETF published in June 2022, defines eight methods. PATCH comes from RFC 5789 (2010). A safe method only reads. An idempotent method has the same effect sent once or ten times, so clients can retry it.
GETRead a resource. Safe and idempotent.
HEADLike GET, but the server sends only the headers. Safe and idempotent.
POSTSend data for the server to process, often to create something. Neither safe nor idempotent: double-click "Pay" at your own risk.
PUTCreate or replace the resource at this URL. Idempotent: ten identical PUTs leave one result.
PATCHApply a partial change. Not idempotent by definition (RFC 5789), although a given patch format can make it so.
DELETERemove the resource. Idempotent: it is just as gone after the second request, even if that one answers 404.
OPTIONSAsk which methods a URL supports. Browsers send it as the CORS preflight.
CONNECT and TRACECONNECT opens a tunnel, usually for HTTPS through a proxy. TRACE echoes the request back for debugging.
HTTP status code lookup
Type a code, or pick a class to list its codes. Names come from the IANA HTTP Status Code Registry (updated 15 September 2025), meanings from RFC 9110 and the RFC each code cites. The jokes are ours.
Try 200, 308, 404, 418, 429 or 503.
Method: the tool holds the 62 named IANA entries (including the temporary 104 and the obsoleted 510) plus 306 and 418, which RFC 9110 marks unused. An unregistered code is treated like the x00 code of its class, as RFC 9110 tells clients to do. Nothing is sent anywhere.
The five classes, and the codes that cause arguments
The first digit is the class. A client that reads only that digit still knows roughly what happened.
2xx: it worked
200 OK is the default. Return 201 Created with a Location header after a POST creates something, and 204 No Content when there is nothing to send back, for example after a DELETE.
3xx: go somewhere else
301 and 308 are permanent; 302 and 307 are temporary. With 301 and 302, clients may turn a POST into a GET; with 307 and 308 they must not. 304 Not Modified tells the client its cached copy is still good.
4xx: you did something wrong
400 means the request is malformed. 404 Not Found says nothing is here right now; 410 Gone says it existed and will not come back. 429 Too Many Requests, added by RFC 6585 in 2012, is rate limiting; a Retry-After header may say how long to wait.
And 418? RFC 2324, the Hyper Text Coffee Pot Control Protocol, published on 1 April 1998, made a teapot asked to brew coffee answer "I'm a teapot".
5xx: we did something wrong
500 is the generic server failure. 502 Bad Gateway and 504 Gateway Timeout come from a proxy whose upstream server sent garbage or nothing. 503 Service Unavailable means "temporarily overloaded or down for maintenance"; like 429, it can carry Retry-After.
Frequently asked questions
What is the difference between 301 and 308?
Both mean the resource moved permanently. With 301, clients may change a POST into a GET when they follow the redirect, for historical reasons. With 308, the client must repeat the same method and body at the new URL.
What is the difference between 401 and 403?
401 Unauthorized means the request has no valid credentials, and the server sends a WWW-Authenticate header that says how to log in. 403 Forbidden means the server understood who you are, or does not care, and still refuses.
Is 418 I'm a teapot a real status code?
It comes from RFC 2324, an April Fools' joke from 1998. RFC 9110 lists 418 as reserved and unused, so it cannot be assigned to anything else, because some software already sends it.
Should an API return 200 with an error message in the body?
No. Use the status code that matches what happened, such as 400, 404, 409 or 422, so that clients, caches and monitoring tools can react without parsing the body.
Sources: RFC 9110 HTTP Semantics (IETF, June 2022); IANA Hypertext Transfer Protocol (HTTP) Status Code Registry (updated 2025-09-15); RFC 5789 (PATCH, 2010); RFC 6585 (428, 429, 431 and 511, 2012); RFC 2324 (1998); Roy Fielding's dissertation (UC Irvine, 2000); MDN Web Docs, HTTP reference.