Representational State Transfer (REST)
An architectural style for networked systems that constrains interactions around resources, representations, stateless messages, and a uniform interface.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/representational-state-transfer/
01What it means
Representational State Transfer (REST) is an architectural style defined by constraints including client-server separation, stateless requests, cacheability, a uniform interface, layered components, and optional downloaded code. In a RESTful system, clients act on resource representations through standardized semantics. REST is not synonymous with any HTTP API that returns JSON.[1][2]
- Client–server
- Separate user interface and data concerns
- Stateless requests
- Each request carries processing context
- Cacheability
- Responses declare reuse semantics
- Layered system
- Intermediaries preserve the interface
- Representations
- Resource state plus available controls
- Code on demand
- Optional downloaded executable code
Returning JSON over HTTP does not by itself make an API RESTful; evaluate the design against the complete constraint set.
02Why it matters
REST's constraints aim to improve evolvability, visibility, scalability, and intermediary support across a distributed system. Shared HTTP semantics can reduce custom protocol knowledge and allow clients, servers, caches, gateways, and monitoring tools to cooperate.
03When to use it
Use REST as a design lens for resource-oriented web APIs that benefit from standard HTTP semantics, stateless scaling, and caching. Event streams, real-time bidirectional sessions, computation-oriented RPC, or highly connected query models may fit other interaction styles better.
04How it works
- Model stable resources and assign each an identifier rather than exposing implementation procedures directly.
- Exchange representations that describe resource state and links or controls available to the client.
- Apply HTTP methods, status codes, headers, and media types according to their standardized semantics.
- Make each request contain the context needed for processing instead of relying on hidden server session state.
- Declare cache behavior and allow layered intermediaries without changing the interface seen by clients.
- Evaluate the design against all REST constraints rather than treating a URL style as sufficient.
05A practical example
A catalog API identifies products with stable URLs. Clients retrieve representations with GET, update supported fields using the documented method, follow links to related resources, and revalidate cached responses with validators, while a gateway can mediate requests transparently.
06Where it breaks
REST constraints impose design discipline but do not guarantee a usable, secure, or reliable API. Strict resource modeling can be awkward for some workflows, stateless messages may repeat context, and many APIs called RESTful implement only a subset of the style.
Common mistakes
- Calling any JSON-over-HTTP interface RESTful regardless of the architectural constraints.
- Encoding every action as a verb in a URL while ignoring standard method semantics.
- Keeping required conversational state only on the server and calling interactions stateless.
- Assuming REST is always preferable to RPC, events, or persistent bidirectional communication.
07Sources
- Architectural Styles and the Design of Network-based Software ArchitecturesRoy Thomas Fielding · Original doctoral dissertationArchitectural Styles and the Design of Network-based Software Architectures
- HTTP Semantics (RFC 9110)RFC Editor · Internet StandardHTTP Semantics (RFC 9110)