Understanding the Richardson Maturity Model and Best Practices for REST API Design

Correct and complete use of REST is challenging because REST, defined by Roy Fielding, is an architectural style rather than a strict specification; Leonard Richardson addressed this gap by proposing the Richardson Maturity Model, which classifies REST implementations into distinct levels.

Level 0 – Using HTTP as a transport shows a simple RPC‑style service where a hospital appointment endpoint receives a document via POST and returns a response containing the requested information. Example request and response are shown:

POST /appointmentService HTTP/1.1
[省略了其他头的信息……]
"2010-01-04" doctor = "mjones" />

HTTP/1.1 200 OK
[省略了其他头的信息……]

The payload can be XML, JSON, YAML, or any custom format. Creating an appointment follows the same pattern with a POST request and a successful 200 response, while a conflict returns a 409 with an error message.

POST /appointmentService HTTP/1.1
[省略了其他头的信息……]
HTTP/1.1 200 OK
[省略了其他头的信息……]

Level 1 – Introducing resources treats each doctor’s schedule as a distinct resource. A POST to /doctors/mjones returns an openSlotList where each slot can be handled individually.

POST /doctors/mjones HTTP/1.1
[省略了其他头的信息……]

HTTP/1.1 200 OK

Creating an appointment then becomes a POST to a specific slot URI, e.g., /slots/1234 , with a 200 response on success.

POST /slots/1234 HTTP/1.1
[省略了其他头的信息……]

HTTP/1.1 200 OK

Level 2 – Using HTTP verbs semantically distinguishes actions by method: GET retrieves resources, POST creates, PUT updates, DELETE removes. The example uses GET to fetch open slots and POST to book an appointment, with appropriate status codes (200, 201, 409, etc.).

GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1
Host: royalhope.nhs.uk

HTTP/1.1 200 OK

When a slot is already taken, the server returns 409 Conflict with a clear error payload.

HTTP/1.1 409 Conflict
[省略了其他头的信息……]

Level 3 – HATEOAS (Hypermedia As The Engine Of Application State) embeds links in responses so clients can discover next actions without hard‑coded URIs. Each slot now includes a link rel="/linkrels/slot/book" uri="/slots/1234" . Booking returns a 201 with a Location header and a set of hypermedia controls for further operations (cancel, addTest, etc.).

GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1
Host: royalhope.nhs.uk

HTTP/1.1 200 OK
POST /slots/1234 HTTP/1.1
[省略了其他头的信息……]

HTTP/1.1 201 Created
Location: http://royalhope.nhs.uk/slots/1234/appointment

The article then lists practical REST API design best practices: use nouns (plural) for resources, avoid verbs in URLs, express relationships with sub‑resources, rely on HTTP headers for content negotiation, apply HATEOAS, provide filtering, sorting, field selection, pagination, simple versioning (e.g., /blog/api/v1 ), and leverage appropriate HTTP status codes for error handling.

/resources
/resources/1024

GET /cars?color=red
GET /cars?seats<=2
GET /cars?sort=-manufactorer,+model
GET /cars?fields=manufacturer,model,id,color
GET /cars?offset=10&limit=5
/blog/api/v1

{
  "errors": [
    {
      "userMessage": "Sorry, the requested resource does not exist",
      "internalMessage": "No car found in the database",
      "code": 34,
      "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
    }
  ]
}

These guidelines help developers build robust, evolvable, and truly RESTful services.