REST Architectural Constraints

Also Known As

TL;DR

Explanation

Roy Fielding's REST dissertation defines six constraints: Stateless (server holds no session state — each request is self-contained), Uniform Interface (consistent resource identification via URIs, manipulation via representations, self-descriptive messages, HATEOAS), Client-Server separation, Cacheable responses, Layered System (client cannot tell if it's talking to a proxy or origin), Code on Demand (optional — return executable code). Most 'REST' APIs violate HATEOAS, making them HTTP APIs rather than truly RESTful. Understanding the constraints explains why stateless APIs scale better.

Common Misconception

Why It Matters

Common Mistakes

• Session-based authentication in a 'REST' API — violates statelessness; use JWT or API keys.
• Verbs in URLs: POST /createUser — REST uses nouns (POST /users); the HTTP method is the verb.
• Ignoring HATEOAS — without links, clients must hardcode URLs; with HATEOAS, the API is self-discoverable.
• Status 200 for errors — violates uniform interface; clients cannot distinguish success from failure without parsing the body.

Code Examples

// Not REST — verbs in URLs, wrong HTTP methods, stateful:
POST /api/getUser?id=42         // Verb in URL, wrong method
POST /api/deleteOrder?id=10     // Should be DELETE /api/orders/10
GET  /api/createProduct         // GET should be read-only
// Session stored on server — violates stateless constraint

// REST-aligned:
GET    /api/users/42          // Get user
POST   /api/users             // Create user
PUT    /api/users/42          // Replace user
PATCH  /api/users/42          // Partial update
DELETE /api/orders/10         // Delete order

// HATEOAS response:
{
  "id": 42,
  "name": "Alice",
  "_links": {
    "self":   {"href": "/api/users/42"},
    "orders": {"href": "/api/users/42/orders"}
  }
}

Tags

Related Terms

References

• https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm