REST API (REST)

REST (Representational State Transfer) is an architectural style for distributed systems defined by Roy Fielding in his 2000 dissertation. A RESTful API models server-side data as resources, each identified by a URI, and manipulated via standard HTTP methods.

REST constraints:

1. Client-server: separation of concerns between UI and data storage
2. Stateless: each request contains all information needed to process it; no server-side session state
3. Cacheable: responses must declare cacheability to improve performance
4. Uniform interface: consistent resource identification, self-descriptive messages, HATEOAS
5. Layered system: client cannot tell whether it is connected to the end server or an intermediary

Resource design patterns:

GET    /api/v1/users          → List users
GET    /api/v1/users/123      → Get user 123
POST   /api/v1/users          → Create a user
PUT    /api/v1/users/123      → Replace user 123
PATCH  /api/v1/users/123      → Partial update user 123
DELETE /api/v1/users/123      → Delete user 123
GET    /api/v1/users/123/posts → List posts by user 123

Response conventions:

• Use appropriate HTTP status codes (2xx success, 4xx client error, 5xx server error)
• Return JSON by default with Content-Type: application/json
• Include pagination metadata for list endpoints (total, page, per_page, next_cursor)
• Use consistent error format: { "error": { "code": "NOT_FOUND", "message": "..." } }

Authentication patterns: API keys (header or query parameter), OAuth 2.0 (bearer tokens), JWT (stateless authentication).

# List resources with pagination
$ curl -s "https://api.example.com/v1/posts?page=1&per_page=3" | jq
{
  "data": [
    { "id": 1, "title": "First Post", "author_id": 123 },
    { "id": 2, "title": "Second Post", "author_id": 456 }
  ],
  "meta": { "total": 42, "page": 1, "per_page": 3 }
}

# Create with POST, get 201 Created
$ curl -s -X POST https://api.example.com/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tok_abc" \
  -d '{"title": "New Post", "body": "Content here"}' \
  -w "\nHTTP Status: %{http_code}\n"
{"id": 43, "title": "New Post", "created_at": "2026-04-15T12:00:00Z"}
HTTP Status: 201

# Error response format
$ curl -s https://api.example.com/v1/posts/9999 | jq
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Post with id 9999 not found"
  }
}