[ADP-315] REST 成熟度

概述

RESTful API 成熟度模型由 Leonard Richardson 提出，用於衡量 API 遵循 REST 原則的程度。該模型分為四個級別: 0 級到 3 級。

指導方針

• API 必須(MUST)達到至少 2 級成熟度。
• API 可以(MAY)在某些情況下提供超媒體資訊，但不是所有情況。參見 ADP-360: 資源擴展 和 ADP-312: 分頁。

成熟度級別

0 級: POX (普通舊式 XML 沼澤)

• 單一端點
• 使用 HTTP 作為傳輸協議
• 通常是 RPC 風格的端點

示例:

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>

1 級: 資源

• 多個端點代表不同的資源
• 每個資源都有自己的 URI
• 仍然使用 HTTP 作為傳輸協議，通常沒有充分利用 HTTP 方法

示例:

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

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

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

2 級: HTTP 動詞

• 充分使用 HTTP 方法 (GET， POST， PUT， DELETE)
• 利用 HTTP 狀態碼進行回應
• 支持內容協商 (例如， JSON， XML)

示例:

創建用戶:

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"
}

更新用戶:

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 /users/123 HTTP/1.1
Host: example.com

HTTP/1.1 204 No Content

3 級: 超媒體控制

• 實現 HATEOAS (超媒體作為應用狀態引擎)
• API 回應包括相關資源和操作的超鏈接
• 通過超媒體提供可發現性

示例:

獲取帶有鏈接的用戶:

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"
}

設計考慮

達到 3 級成熟度

在實現需要 API 連結性的場景（如分頁）的 3 級成熟度（HATEOAS）時：

1. 使用標準 Link 標頭

   • 優先使用 RFC 8288 中定義的標準 HTTP Link 標頭，而非非標準格式如 HAL
   • Link 標頭提供了在 HTTP 回應中包含超鏈接的標準化方式

   分頁示例：

   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. 自定義標頭用於擴展功能

   • 當標準 Link 標頭不足以描述時，可以(MAY)使用自定義標頭來提供額外的超媒體控制資訊，如分頁資訊中的總數量
   • 自定義標頭必須(MUST)在組織的內部註冊表中註冊
   • 自定義標頭應(SHOULD)遵循 ADP-364: 自定義標頭設計 的命名慣例

參考資料

• Richardson 成熟度模型