[ADP-315] REST maturity

Overview

The RESTful API Maturity Model, proposed by Leonard Richardson, measures the extent to which an API adheres to REST principles. The model is divided into four levels: Level 0 to Level 3.

Guidance

• APIs MUST achieve at least Level 2 Maturity.
• APIs MAY provide hypermedia information in certain cases but not all. See ADP-360: Resource Expansion and ADP-312: Pagination.

Maturity Levels

Level 0: The Swamp of POX (Plain Old XML)

• Single endpoint
• Uses HTTP as a transport protocol
• Typically, RPC-style endpoints

Example:

POST /api HTTP/1.1
Host: example.com
Content-Type: application/xml

<request>
  <action>getUser</action>
  <userId>123</userId>
</request>

HTTP/1.1 200 OK
Content-Type: application/xml

<response>
  <user>
    <id>123</id>
    <name>John Doe</name>
  </user>
</response>

Level 1: Resources

• Multiple endpoints representing different resources
• Each resource has its own URI
• Still uses HTTP as a transport protocol, often without full use of HTTP methods

Example:

GET /users/123 HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "John Doe"
}

Level 2: HTTP Verbs

• Full use of HTTP methods (GET, POST, PUT, DELETE)
• Utilizes HTTP status codes for responses
• Supports content negotiation (e.g., JSON, XML)

Examples:

Create a User:

POST /users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "John Doe"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/123

{
  "id": 123,
  "name": "John Doe"
}

Update a User:

PUT /users/123 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "John Smith"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "John Smith"
}

Delete a User:

DELETE /users/123 HTTP/1.1
Host: example.com

HTTP/1.1 204 No Content

Level 3: Hypermedia Controls

• Implements HATEOAS (Hypermedia As The Engine Of Application State)
• API responses include hyperlinks to related resources and actions
• Provides discoverability through hypermedia

Example:

Get User with Links:

GET /users/123 HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json
Link: </users/123>; rel="self", </users/123/friends>; rel="friends", </users/123/posts>; rel="posts"

{
  "id": 123,
  "name": "John Doe"
}

Design Considerations

To ensure that APIs achieve at least Level 2 maturity, the following guidelines MUST be followed:

1. Resource Identification through URIs
   • Each resource MUST have a unique URI
   • URIs SHOULD be logical and consistent
2. Utilization of HTTP Methods
   • See ADP-110: HTTP Methods
3. Proper Use of HTTP Status Codes
   • See ADP-200: HTTP Status Codes
4. Appropriate Use of HTTP Headers
   • See ADP-120: HTTP Headers
5. Effective Use of Query Parameters
   • See ADP-359: Query Parameters

Achieving Level 3 Maturity

When implementing Level 3 maturity (HATEOAS) for scenarios requiring API linkability such as pagination:

1. Use Standard Link Headers

   • Prefer standard HTTP Link headers as defined in RFC 8288 instead of non-standard formats like HAL
   • Link headers provide a standardized way to include hyperlinks in HTTP responses

   Example for pagination:

   HTTP/1.1 200 OK
   Content-Type: application/json
   Link: </users?page=3>; rel="next", </users?page=1>; rel="prev", </users?page=10>; rel="last", </users?page=1>; rel="first"

2. Custom Headers for Extended Functionality

   • When standard Link headers are insufficient, custom headers MAY be used for additional hypermedia controls
   • Custom headers MUST be registered in the organization's internal registry
   • Follow ADP-364: Custom Header Fields Design for naming conventions

References

• Richardson Maturity Model

Changelog

• 2025-04-14: Updated to recommend standard Link headers and custom headers for pagination metadata instead of embedding links in response body.