[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.

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

{
  "id": 123,
  "name": "John Doe",
  "links": {
    "self": "/users/123",
    "friends": "/users/123/friends",
    "posts": "/users/123/posts"
  }
}

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

Versioning and Compatibility

When evolving APIs, consider the following:

• Follow ADP-24: Versioning Mechanism for API versioning
• Maintain backwards compatibility when possible
• Clearly communicate changes and deprecations to API consumers

Security Considerations

• Implement appropriate authentication and authorization mechanisms
• Use HTTPS for all API endpoints

Related ADPs

• ADP-110: HTTP Methods
• ADP-120: HTTP Headers
• ADP-200: HTTP Status Codes
• ADP-359: Query Parameters
• ADP-360: Resource Expansion
• ADP-24: Versioning Mechanism
• ADP-20: Engineering Principles
• ADP-322: Hypermedia API alternative

References

• Richardson Maturity Model