[ADP-315] REST 成熟度

概述

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

指導方針

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

成熟度級別

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

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

設計考慮

為確保 API 達到至少 2 級成熟度，必須遵循以下準則:

1. 通過 URI 識別資源
   • 每個資源必須有一個唯一的 URI
   • URI 應該是邏輯的和一致的
2. 利用 HTTP 方法
   • 參見 ADP-110: HTTP 方法
3. 正確使用 HTTP 狀態碼
   • 參見 ADP-200: HTTP 狀態碼
4. 適當使用 HTTP 標頭
   • 參見 ADP-120: HTTP 標頭
5. 有效使用查詢參數
   • 參見 ADP-359: 查詢參數

版本控制和兼容性

在演進 API 時，請考慮以下事項:

• 遵循 ADP-24: 版本控制機制 進行 API 版本控制
• 盡可能保持向後兼容
• 明確向 API 消費者傳達變更和棄用資訊

安全考慮

• 實施適當的身份驗證和授權機制
• 對所有 API 端點使用 HTTPS

相關 ADP

• ADP-110: HTTP 方法
• ADP-120: HTTP 標頭
• ADP-200: HTTP 狀態碼
• ADP-359: 查詢參數
• ADP-360: 資源擴展
• ADP-24: 版本控制機制
• ADP-20: 工程原則
• ADP-322: 超媒體替代方案

參考資料

• Richardson 成熟度模型