HATEOAS and Richardson Maturity Model

The Richardson Maturity Model grades REST APIs from Level 0 (single endpoint, RPC style) through Level 1 (multiple resources), Level 2 (HTTP verbs and status codes), to Level 3: Hypermedia (HATEOAS). Most production APIs reach Level 2. HATEOAS (Hypermedia as the Engine of Application State) means responses embed links to related actions. A client that understands hypermedia can navigate the entire API without hardcoded URLs. The HAL (Hypertext Application Language) and JSON:API formats are popular ways to implement this.

Example

# Level 2 response (typical production API)
# GET /orders/55
# HTTP/1.1 200 OK
# {
#   "id": 55,
#   "status": "PENDING",
#   "total": 149.99,
#   "customerId": 7
# }

# Level 3 response (HATEOAS with HAL)
# GET /orders/55
# HTTP/1.1 200 OK
# Content-Type: application/hal+json
{
  "id": 55,
  "status": "PENDING",
  "total": 149.99,
  "_links": {
    "self":   { "href": "/orders/55" },
    "cancel": { "href": "/orders/55/cancel", "method": "POST" },
    "pay":    { "href": "/orders/55/payment", "method": "POST" },
    "customer": { "href": "/users/7" },
    "items":  { "href": "/orders/55/items" }
  },
  "_embedded": {
    "customer": {
      "id": 7,
      "name": "Alice",
      "_links": { "self": { "href": "/users/7" } }
    }
  }
}

# The client discovers available actions from _links —
# no hardcoded URL knowledge required.
# If order is already CANCELLED, the "cancel" link is absent.

HTML

Full Editor

Related Resources

REST API Reference

Complete tag & property list

REST API How-To Guides

Step-by-step practical guides

REST API Exercises

Practice what you've learned