REST: Resource, Representation and Uniform Interface

Objectives

By the end of the lesson, you can explain the architectural constraints of REST, distinguish a REST-style HTTP API from a "JSON over HTTP" solution, and characterise it along the seven aspects.

Why is it needed?

Between services the meaning of the call and the common rules must be agreed. REST is not a concrete API format but an architectural style, whose goal is for components to communicate in a uniform, easily observable and cacheable way. It was described in Roy Fielding's doctoral dissertation.

What is REST?

According to Fielding, REST (Representational State Transfer) is a set of constraints:

• client–server: separation of concerns;
• stateless: each request must contain the information necessary to understand it;
• cacheable: responses mark whether they are cacheable;
• uniform interface: identification of resources, manipulation of resources through representations, self-descriptive messages, and hypermedia as the engine of application state;
• layered system: components may consist of hierarchical layers;
• code on demand: an optional constraint.

A resource is anything that can be identified (an order, a collection). The client receives the representation of the resource, not the internal object or database row. The same resource can appear in several formats; Content-Type and the agreement on accepted formats make the content interpretable.

sequenceDiagram
  participant K as Client
  participant S as Server
  K->>S: GET /orders/42 (Accept: application/json)
  S-->>K: 200, the JSON representation of the resource

Methods and intent

Based on RFC 9110, GET has read intent and is safe and idempotent; PUT and DELETE are idempotent; POST asks for processing tied to the resource and is not idempotent. Repeating or prefetching a safe method does not need to cause a business change, so browsers, caches and intermediaries may prefetch or re-request it. A business modification must therefore not be expressed with GET.

"REST" and "REST-style HTTP API"

In practice many "REST APIs" work with noun-style paths and JSON, but use little hypermedia. It is therefore more precise to speak of a REST-style HTTP API and to name which constraints it implements. The shape of the path alone does not fulfil the architectural constraints. Stateless means that the client context needed to process the request does not come from a hidden earlier conversation; the server may have persistent business state (for example a reservation), and using a database does not violate the constraint.

Characteristics

Aspect	REST-style HTTP API
Direction	Two-way message exchange, but per request; the server does not send by itself
Initiator	Always the client
Connection persistence	A new or reused connection per request; the protocol is stateless
Latency	One request–response path; detecting a change is delayed until the next request
Load	Proportional to the number of requests; a cache can reduce it
Fault tolerance	Simple: a failed request can be repeated if idempotent (6.5)
When it fits	Resource-oriented, well-cacheable services with many consumers
When it does not	Many kinds of complex queries, aggregation needing many calls, changes arriving from the server side

Why is this useful between services?

HTTP is widely supported, requests and responses are easy to observe, and the protocol provides statuses, caching and conditional-request tools. In return, the resource model is not natural for every operation, and querying several related pieces of data can cause many calls (6.3).

Common misconceptions

Statement	Clarification
"REST = JSON over HTTP."	REST is a set of constraints; JSON and HTTP are only one implementation.
"A stateless API has no database."	The context per request is not hidden; business state can be persistent.
"A noun-style path makes the API REST."	The shape of the path does not fulfil the constraints.
"Repeating a DELETE means an error."	It is idempotent: the effect is the same, the response can differ.

In short

• REST is a set of architectural constraints: client–server, stateless, cacheable, uniform interface, layered system.
• The client receives a representation, not an internal object.
• In practice the REST-style HTTP API is common, with little hypermedia.
• The initiator is always the client; for changes arriving from the server side another method is needed.

Review questions

1. What are the constraints of REST, and which is optional?
2. Why is a stateless API not in contradiction with persistent business state?
3. Why is it dangerous to express a purchase with a GET?

Learning resources

• Roy Fielding: REST architectural style (dissertation, chapter 5) — the original description of the constraints.
• RFC 9110: HTTP Semantics — the meaning of methods and statuses.