A REST API is an application programming interface (API) designed around the architectural constraints of Representational State Transfer (REST). It lets clients interact with identified resources by exchanging representations of them, commonly over HTTP. REST is an architectural style, not a protocol or data format.
Resources, Requests and Responses
In a REST API, a client addresses a resource using a uniform resource identifier (URI) and sends a request. A resource is the thing being identified, such as a document or collection; a representation is information describing its current or intended state. JSON is common, but representations can use XML, text, images or other formats.
With HTTP, the method expresses the request's intent. GET retrieves a representation; POST requests resource-specific processing, often creating a resource. PUT creates or replaces the target resource's state, while DELETE removes the target URI's association with its current functionality; it does not guarantee that all underlying data is erased. The server processes the request and returns a status code and headers, plus a representation when appropriate. Some successful responses have no body, and error responses may explain why a request failed. These method semantics are broader than a simple create, read, update and delete (CRUD) mapping.
Statelessness and Stored Data
Statelessness means that each request provides the context needed to process it, without depending on server-held conversational session context from previous requests. A REST API can still use databases, retain resource data and authenticate requests. The restriction concerns conversation state, not all server-side storage.
For example, a hypothetical client retrieving successive pages of results supplies the relevant page number with each request. The server should not need to remember which page that client viewed last. Credentials or authorization information can accompany each request where access control requires them; statelessness does not mean anonymous or unprotected access.
Looking for liquidity, exploring on-ramp/off-ramp services, or seeking expert guidance?
Get startedThe Uniform Interface
The uniform interface of a REST API means more than consistent endpoint names or familiar HTTP methods. It requires identifiable resources, manipulation of those resources through representations, self-descriptive messages and hypermedia that guides further interactions. Self-descriptive messages carry information needed to interpret them, such as a representation's media type and applicable cache controls.
Hypermedia means that representations include links or controls indicating available next steps, rather than requiring the client to construct every possible interaction from separately documented URI patterns. Many interfaces described as RESTful implement only part of these constraints. A JSON-over-HTTP interface can therefore be resource-oriented without fully satisfying REST.
Core REST constraints and what they mean
| Option | Description / design intent | Definition / role in REST |
|---|---|---|
| Client–server architecture | Description / design intentSeparates user interface concerns from data storage concerns to allow independent evolution | Definition / role in RESTthe client and server are separate entities that interact through a uniform interface |
| Statelessness | Description / design intentEach request must contain all information needed; servers do not store session state between requests | Definition / role in RESTEach client request to a REST API must contain all the necessary information for the server to fulfill the request |
| Cacheability | Description / design intentResponses provide implicit or explicit cacheability information so clients and intermediaries can determine whether reuse is permitted | Definition / role in RESTCacheability can be identified implicitly or explicitly; it is not limited to an explicit label on every response |
| Uniform interface | Description / design intentEnsures consistent interactions using resource identification, self-descriptive messages, and standard HTTP verbs | Definition / role in RESTA uniform interface is a fundamental aspect of RESTful API design |
| Layered system | Description / design intentSupports organizing components into layers and introducing intermediaries like API gateways | Definition / role in RESTA RESTful system can be composed of multiple layers, each with its own responsibilities |
| Code on demand (optional) | Description / design intentOptionally allows servers to send executable code that extends client functionality | Definition / role in RESTREST allows for the optional transfer of executable code from the server to the client |
Client–Server Separation and Cacheability
Client–server separation keeps presentation and interaction concerns distinct from resource storage and processing. A REST API can support independent changes to clients and servers when their interface contract remains compatible. A layered system also allows intermediaries, such as gateways or caches, to participate without exposing the whole architecture to the client.
Cacheability determines whether a response may be reused for a later request and under what conditions. HTTP cache rules can permit reuse, require validation or prevent storage; not every response should be cached. Reuse can reduce repeated transfers or processing, but its benefit depends on freshness requirements and workload. Neither caching nor statelessness guarantees speed, scalability or reliability: those outcomes depend on the implementation and how it is used.
Consistent URI naming and filtering options help clients identify resources and request relevant subsets. Documentation should explain requests, representations, errors and authentication options, such as API keys or access tokens. Credentials need suitable transport protection, and authorization controls which operations a requester may perform. A versioning approach communicates incompatible interface changes. These choices support usability and security; they are not additional REST constraints.
