Understanding REST Architecture and Its Constraints

In recent years REST APIs have become increasingly popular, especially with the widespread adoption of micro‑services. REST, which stands for Representational State Transfer, was introduced by Roy Fielding as an architectural style that defines a set of constraints any compliant system must satisfy.

To use RESTful architecture correctly, one must first understand what REST means. The term can be broken down into “representation” and “state transfer”.

1) Representation

Resources are the core of REST. Every object that can be referenced is a resource and is identified by a URI. A representation is a particular form of that resource (e.g., a JPEG image, a JSON document, or an XML file). In REST, the client and server exchange only representations of resources.

2) State Transfer

State can be divided into application state (maintained by the client) and resource state (stored on the server). The client changes resource state by sending a request (method, URI, and representation) that creates, updates, reads, or deletes the resource, causing a state transition that is reflected in the representation.

3) Conclusion

The client uses REST API calls to manipulate resources, which triggers state transitions that are expressed through representations.

When Does an API Conform to the REST Style?

Roy Fielding derived the REST style by progressively adding constraints to an abstract architecture. An API must satisfy all of the following constraints:

Uniform Interface

Stateless

Cache

Client‑Server

Layered System

Code‑on‑Demand (optional)

1. Uniform Interface

The uniform interface is the most visible constraint and includes several aspects:

Resource URI

Request parameters

Request methods

Status codes

Response content

1) Resource URI

Resources should be identified by nouns (usually plural) and never contain verbs. An identifier (ID) is placed in the URI when a specific resource is addressed.

http://www.example.com/books          // collection of all books
http://www.example.com/books/123      // book with ID 123
http://www.example.com/books/query      // NOT RESTful (action in URI)
http://www.example.com/buy               // NOT RESTful (verb in URI)

2) Request Parameters

Filtering, pagination, and other non‑identifying data belong in query parameters, while the resource identifier stays in the path.

http://www.example.com/books/123                // GET a specific book
http://www.example.com/books/Fielding?page=1&per_page=10   // filter by author, pagination

3) Request Methods

REST uses standard HTTP verbs, but the mere presence of GET/POST/PUT/DELETE does not guarantee compliance. Their semantics are:

GET – retrieve a resource.

POST – create a new resource; the server decides the URI.

PUT – create or replace a resource; the client decides the URI.

DELETE – remove a resource.

Less common methods include HEAD (metadata only) and PATCH (partial updates).

4) Status Codes

Standard HTTP status codes convey the result of a request. Common ones include 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401/403 (Unauthorized/Forbidden), 404 (Not Found), 405 (Method Not Allowed), 409 (Conflict), 500 (Internal Server Error), etc.

5) Response Content

The response body must be a representation of the requested resource, typically JSON or XML, and the Content‑Type header must indicate the format.

2. Stateless

Each request must contain all the information needed to understand and process it; the server does not store client context between requests. Authentication information is usually sent in each request header.

3. Cache

Caching responses improves efficiency and scalability. Responses must be explicitly marked as cacheable or non‑cacheable.

4. Client‑Server

This constraint separates the user interface from data storage, allowing independent evolution of clients and servers.

5. Layered System

The architecture can be composed of hierarchical layers, each with its own responsibilities, which simplifies design and enables intermediaries.

6. Code‑on‑Demand (optional)

Clients may request executable code from the server to extend functionality, though this reduces visibility and is optional.