# Representational State Transfer \(REST\)

An architectural style for networked systems that constrains interactions around resources, representations, stateless messages, and a uniform interface.

- Type: framework
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/representational-state-transfer/>)

## What 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.

## Why 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.

## When 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.

## How it works

1. Model stable resources and assign each an identifier rather than exposing implementation procedures directly.
2. Exchange representations that describe resource state and links or controls available to the client.
3. Apply HTTP methods, status codes, headers, and media types according to their standardized semantics.
4. Make each request contain the context needed for processing instead of relying on hidden server session state.
5. Declare cache behavior and allow layered intermediaries without changing the interface seen by clients.
6. Evaluate the design against all REST constraints rather than treating a URL style as sufficient.

## A 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/representational-state-transfer/#visualization-representational-state-transfer>)

## Sources

1. [Architectural Styles and the Design of Network-based Software Architectures](<https://roy.gbiv.com/pubs/dissertation/top.htm>) — Roy Thomas Fielding · Original doctoral dissertation
2. [HTTP Semantics \(RFC 9110\)](<https://www.rfc-editor.org/rfc/rfc9110>) — RFC Editor · Internet Standard

## Related topics

- [Application Programming Interface \(API\)](<https://wiki.soroush.uk/topic/application-programming-interface/>)
- [HTTP](<https://wiki.soroush.uk/topic/http/>)
- [HTTP Method](<https://wiki.soroush.uk/topic/http-method/>)
