REST — Glossary

REST stands for Representational State Transfer, an architectural style for distributed hypermedia systems defined by Roy Fielding in chapter 5 of his 2000 doctoral dissertation. It is a set of constraints, not a protocol or a format. Most developers meet it as "REST APIs" built on HTTP with JSON bodies, which usually follow only part of the original style.

How it works

Fielding builds REST by adding constraints one at a time to the null style, which has none. The result has five required constraints and one optional one.

Client-server: separates the user interface from data storage, so each side can evolve on its own.
Stateless: each request carries everything the server needs to understand it. Session state stays on the client.
Cache: responses are labeled cacheable or non-cacheable, so clients can reuse them.
Uniform interface: the feature that most separates REST from other styles. It has four sub-constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, and hypermedia as the engine of application state (HATEOAS).
Layered system: a client sees only the layer it talks to, which allows proxies, gateways and shared caches.
Code-on-demand: the client may download scripts or applets. The dissertation marks this one as optional.

In practice, a resource has a URL, the method says what to do, and the status code says what happened. This local server returns a resource with links to what the client can do next, then deletes it. The grep keeps only the status line, two headers and the body:

$ curl -si localhost:8099/orders/42 | grep -E '^(HTTP|Content-Type|Cache-Control|\{)'
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60
{"id":42,"status":"pending","_links":{"self":{"href":"/orders/42"},"cancel":{"href":"/orders/42","method":"DELETE"},"pay":{"href":"/orders/42/payment","method":"PUT"}}}

$ curl -si -X DELETE localhost:8099/orders/42 | grep ^HTTP
HTTP/1.1 204 No Content
$ curl -si localhost:8099/orders/42 | grep ^HTTP
HTTP/1.1 404 Not Found

The _links shape above is one convention chosen for this demo. REST does not prescribe a link format.

What is the difference between REST and RESTful?

There is no formal difference. People use "RESTful" to mean an API that follows REST, and "REST API" for the same thing. Fielding wrote in 2008 that if the engine of application state is not driven by hypertext, the API cannot be RESTful. By that standard, many JSON-over-HTTP APIs are better described as HTTP APIs.

Common pitfalls

Calling every HTTP API REST: an API that fixes URL templates in client code and has no hypermedia fails the hypermedia sub-constraint. Say "HTTP API" if that is what you built.
Storing session state on the server: a server-side session breaks the stateless constraint, which Fielding adds to improve visibility, reliability and scalability. Each request must carry everything the server needs, such as credentials.
Verbs in URLs: /deleteOrder?id=42 puts the action in the identifier. Use DELETE on /orders/42, and a repeated DELETE has the same intended effect, as RFC 9110 defines for idempotent methods.
Ignoring cache labels: without Cache-Control or similar headers, intermediaries cannot tell what is safe to reuse.
Always returning 200: an error wrapped in a 200 response hides failures from monitoring and caches. Return a real status such as 404, as above.
Treating REST and GraphQL as the same thing: REST gives each resource its own URL, while a GraphQL service usually serves all requests from a single endpoint such as /graphql.

Related terms

HTTP — the protocol most REST APIs run on.
Idempotent — RFC 9110 lists PUT, DELETE and the safe methods as idempotent.
JSON — the usual representation format in REST APIs.
GraphQL — an alternative API style with one endpoint.
Webhook — a server-to-server callback that complements polling REST endpoints.

How it works

What is the difference between REST and RESTful?

Common pitfalls

Related terms

See also