What are the core principles of REST, and how do HTTP methods map to CRUD operations? What makes an API truly RESTful?

Question

Accepted Answer

## REST Principles

REST (Representational State Transfer) is an architectural style for designing networked applications. A truly RESTful API follows these six guiding principles:

### 1. Client-Server Architecture

The client and server are separate entities. The client handles the user interface, while the server manages data storage. This separation allows each to evolve independently.

### 2. Statelessness

Each request from the client must contain all the information needed to process it. The server does not store any client context between requests.

```
# Bad: Server remembers the user from a previous request.
GET /next-page

# Good: Request is self-contained.
GET /products?page=2&limit=10
Authorization: Bearer <token>
```

### 3. Cacheability

Responses must define themselves as cacheable or non-cacheable. Proper caching reduces server load and improves performance.

```
Cache-Control: max-age=3600
ETag: "abc123"
```

### 4. Uniform Interface

Resources are identified by URIs, and actions are performed using standard HTTP methods. This consistency makes APIs predictable.

### 5. Layered System

The architecture can include intermediaries like load balancers, proxies, or gateways. The client does not know whether it is connected directly to the server or through an intermediary.

### 6. Code on Demand (Optional)

Servers can temporarily extend client functionality by transferring executable code, such as JavaScript.

## HTTP Methods and CRUD Operations

| HTTP Method | CRUD Operation | Description | Idempotent |
|-------------|----------------|-------------|------------|
| GET | Read | Retrieve a resource | Yes |
| POST | Create | Create a new resource | No |
| PUT | Update (Full) | Replace an entire resource | Yes |
| PATCH | Update (Partial) | Modify part of a resource | No* |
| DELETE | Delete | Remove a resource | Yes |

*PATCH can be idempotent depending on implementation.

## Idempotency Explained

An operation is idempotent if making the same request multiple times produces the same result.

```
# Idempotent: PUT replaces the resource entirely.
PUT /users/123
{ "name": "Alice", "email": "alice@example.com" }

# Not idempotent: POST creates a new resource each time.
POST /users
{ "name": "Bob" }  # Creates user 124, then 125, then 126...
```

## RESTful URI Design

```
# Good: Nouns represent resources.
GET    /users          # List all users
GET    /users/123      # Get user 123
POST   /users          # Create a new user
PUT    /users/123      # Update user 123
DELETE /users/123      # Delete user 123

# Bad: Verbs in URIs.
GET /getUsers
POST /createUser
DELETE /deleteUser/123
```

## What Makes an API Truly RESTful

Many APIs claim to be RESTful but only partially follow the principles. A truly RESTful API:

- Uses proper HTTP methods for their intended purposes.
- Returns appropriate status codes (200, 201, 404, 500, etc.).
- Is stateless—no session stored on the server.
- Uses hypermedia links to guide clients (HATEOAS).