REST — architectural style for distributed hypermedia systems. Its limitations are not tied solely to HTTP, but in practice REST APIs are most often built on top of HTTP. An API that follows the constraints of REST is called a RESTful API.
REST Limitations
REST defines five mandatory constraints and one optional constraint.
Client-server
The client is responsible for the user interface and user experience, the server is responsible for the data and business capabilities. This separation allows parts of the system to be developed and scaled independently.
No session state on the server
Each client request must contain all the information necessary for the server to understand and process it. The server does not rely on the client session context saved between requests.
This does not mean that the server does not store user data or use a database or cache. The constraint applies specifically to the interaction context that is needed to process the next request.
Caching
The response must explicitly or implicitly determine whether it can be cached. Correct caching reduces latency and load, but requires taking into account the relevance and rules for reusing the response.
Consistent interface
This is the central limitation of REST. It includes four parts:
- resource identification: a resource has a stable identifier, usually a URI;
- control via views: the client receives a representation of the resource and sends representations or instructions to change its state;
- self-describing messages: the message contains enough metadata for the recipient to understand how to process it;
- hypermedia as the engine of application state (HATEOAS): responses inform the client of available further actions through links and controls.
Multi-level system
The client is not required to know whether it is interacting with the end service directly or through a proxy, gateway, cache, or other intermediate layer. Each component sees only neighboring layers.
Code on demand - optional
The server can temporarily extend the functionality of the client by passing executable code, such as JavaScript. This is the only optional REST constraint.
REST and HTTP API
Not every JSON API over HTTP is RESTful. In practice, teams often use isolated REST ideas—resources, uniform URIs, HTTP method semantics, and caching—without fully implementing HATEOAS. It is important to explicitly agree on the style of the API and not use the word REST as a synonym for any HTTP API.
OpenAPI and Swagger
OpenAPI — a machine-readable specification for describing the HTTP API: operations, parameters, data schemas, responses, and security mechanisms. It doesn't just apply to RESTful APIs.
Swagger - a family of tools around OpenAPI, including Swagger UI and Swagger Editor. OpenAPI - specification, Swagger - tools and historical name of the specification until version 3.0.
Primary sources
- Roy Fielding: Architectural Styles and the Design of Network-based Software Architectures
- RFC 9110: HTTP Semantics
- OpenAPI Specification