What REST Really Means

REST stands for Representational State Transfer. It was introduced by Roy Fielding as an architectural style based on constraints for distributed systems.

A RESTful system is not simply an API that uses JSON, HTTP, and URLs. REST has architectural constraints including client-server separation, statelessness, cacheability, a uniform interface, layered systems, and optionally code-on-demand. HATEOAS is part of the uniform-interface constraint.

Many APIs are better described as HTTP APIs rather than strictly RESTful APIs because they use HTTP but do not implement all REST constraints. This distinction matters when discussing architecture precisely.

Client-server: UI concerns and data concerns are separated.

Stateless: Every request contains the information required to process it. The server does not rely on conversational session state stored between requests.

Cacheable: Responses explicitly or implicitly indicate whether they may be cached.

Uniform interface: Resources are identified consistently, representations are transferred, messages are self-descriptive, and hypermedia can drive application state.

Layered system: A client does not need to know whether it is communicating directly with the origin server or through proxies, gateways, CDNs, and other intermediaries.

Code-on-demand: Servers may optionally transfer executable code to clients. This constraint is optional.

Statelessness does not mean that the application has no state. Databases contain state, caches contain state, and users have persistent data. It means the server does not depend on hidden conversational state from a previous request to understand the current request.

For example, if a request contains a bearer token, the server can validate the token and determine the caller without depending on an in-memory session on a particular server instance.

Stateless APIs simplify horizontal scaling because any healthy server instance can process the request.