What is REST? Slightly confused

Understanding REST: A Comprehensive Guide for Developers

Demystify REST (Representational State Transfer) and learn its core principles, architectural constraints, and how it powers modern web services.

REST, or Representational State Transfer, is an architectural style for designing networked applications. It's not a protocol or a standard in itself, but rather a set of guidelines and constraints that, when followed, lead to a scalable, maintainable, and reliable system. If you've ever interacted with a web API, chances are you've used a RESTful service. This article aims to clarify what REST is, why it's so widely adopted, and its fundamental principles.

What is REST and Why is it Important?

At its heart, REST defines how clients and servers communicate over the web. It treats server-side data as 'resources' that can be accessed and manipulated using a uniform, stateless interface. The primary goal of REST is to improve the performance, scalability, and simplicity of web services. It achieves this by leveraging existing web standards and protocols, most notably HTTP.

Before REST became prevalent, other architectural styles like SOAP (Simple Object Access Protocol) were common. While SOAP is powerful, it often involves more complexity, heavier payloads (XML), and tighter coupling between client and server. REST, in contrast, promotes a simpler, more flexible approach, often using lighter data formats like JSON or XML and standard HTTP methods.

flowchart TD
    A[Client] -->|Request (HTTP)| B[Server]
    B -->|Process Request| C{Resource Identified?}
    C -->|Yes| D[Access Resource]
    D -->|Retrieve/Manipulate Data| E[Generate Representation]
    E -->|Response (HTTP + Data)| A
    C -->|No| F[Error (e.g., 404 Not Found)]
    F -->|Error Response| A

Basic Client-Server Interaction in a RESTful System

The Six Core Architectural Constraints of REST

Roy Fielding, in his doctoral dissertation, defined six guiding constraints that characterize a RESTful system. Adhering to these constraints is what makes an API truly RESTful, rather than just 'HTTP-based'.

1. Client-Server: This constraint separates the concerns of the user interface (client) from the data storage (server). This separation improves portability of the UI across multiple platforms and improves scalability by simplifying server components.
2. Stateless: Each request from client to server must contain all the information necessary to understand the request. The server should not store any client context between requests. This improves scalability, reliability, and visibility.
3. Cacheable: Responses from the server must explicitly or implicitly define themselves as cacheable or non-cacheable. This allows clients and intermediaries to cache responses, reducing server load and improving performance.
4. Uniform Interface: This is the most crucial constraint. It simplifies the overall system architecture and improves visibility of interactions. It's broken down into four sub-constraints:
   • Identification of Resources: Resources are identified by URIs (Uniform Resource Identifiers).
   • Manipulation of Resources Through Representations: Clients interact with resources by exchanging representations (e.g., JSON, XML) of those resources.
   • Self-descriptive Messages: Each message includes enough information to describe how to process the message.
   • Hypermedia as the Engine of Application State (HATEOAS): This means that clients should find all available actions and transitions for a resource within the resource's representation itself, typically through links.
5. Layered System: A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. This allows for the introduction of proxies, load balancers, and gateways without affecting the client or server.
6. Code-On-Demand (Optional): Servers can temporarily extend or customize client functionality by transferring executable code (e.g., JavaScript applets). This constraint is optional.

RESTful API Design Principles and HTTP Methods

RESTful APIs typically use standard HTTP methods to perform CRUD (Create, Read, Update, Delete) operations on resources. Here's a common mapping:

• GET: Retrieve a resource or a collection of resources. It should be idempotent and safe (no side effects).
• POST: Create a new resource. It is not idempotent.
• PUT: Update an existing resource or create one if it doesn't exist (full replacement). It is idempotent.
• PATCH: Partially update an existing resource. It is idempotent.
• DELETE: Remove a resource. It is idempotent.

Resources are identified by clear, hierarchical URIs. For example, /users might represent a collection of users, and /users/123 might represent a specific user with ID 123. The representation of these resources is typically JSON or XML.

GET /users HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

Example of a GET request to retrieve a collection of users

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Charlie",
  "email": "charlie@example.com"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/3

{
  "id": 3,
  "name": "Charlie",
  "email": "charlie@example.com"
}

Example of a POST request to create a new user