大多數 RESTful API 其實並不真正符合 REST 原則

文章核心觀點

REST 的真正定義

Roy Thomas Fielding 在其 2000 年的博士論文中定義了 REST（Representational State Transfer）作為一個架構風格，而不是簡單的 CRUD 操作或 HTTP 動詞的使用規範。

HATEOAS：被忽視的核心原則

HATEOAS（Hypermedia as the Engine of Application State） 是 REST 的基本原則，要求用戶端透過伺服器回應中嵌入的超媒體連結動態發現操作和互動，而不是依賴外部文件。

HATEOAS 範例：

{
  "orderId": 123,
  "status": "pending",
  "amount": 99.99,
  "_links": {
    "self": { 
      "href": "/orders/123",
      "method": "GET"
    },
    "cancel": { 
      "href": "/orders/123/cancel", 
      "method": "POST" 
    },
    "payment": {
      "href": "/orders/123/payment",
      "method": "POST"
    }
  }
}

什麼是「資源」？

根據 Fielding 的定義和 RFC 3986，資源的概念遠比大多數人理解的更廣泛：

重要概念：資源不等同於資料庫實體或持久化物件，它是一個概念性的對應，可以是任何能被 URI 唯一識別的東西。

資源的範例：

// 靜態文件
https://api.example.com/documentation

// 動態資料
https://api.example.com/weather/taipei/today

// 集合資源
https://api.example.com/users

// 特定實例
https://api.example.com/users/123

// 關聯資源
https://api.example.com/users/123/orders

// 時間相關資源
https://api.example.com/reports/monthly/2025/01

常見的誤解

Fielding 的六大 RESTful API 規則

1. 不依賴單一通信協議
   API 應該能使用任何 URI 方案，不僅限於 HTTP
2. 不改變通信協議
   遵循現有標準如 HTTP，不要重新定義其行為
3. 專注於媒體類型，而非 URI
   定義數據格式和超媒體控制，而不是 URI 結構
4. 不要硬編碼 URI 結構
   用戶端應該透過伺服器提供的連結動態發現 URI
5. 避免資源「類型」
   伺服器內部的資源分類對用戶端應該是不可見的
6. 從書籤開始，跟隨連結
   用戶端只需要知道起始 URI 和標準媒體類型

實際應用範例：

// 用戶端只知道入口點
GET https://api.example.com/

// 伺服器回應包含可用的操作連結
{
  "welcome": "Welcome to Our API",
  "_links": {
    "users": { "href": "/users" },
    "orders": { "href": "/orders" },
    "products": { "href": "/products" }
  }
}

// 用戶端跟隨連結，而不是建構 URL
GET https://api.example.com/users

// 每個資源都包含其可用操作
{
  "users": [...],
  "_links": {
    "self": { "href": "/users" },
    "create": { "href": "/users", "method": "POST" },
    "search": { "href": "/users/search{?q}", "templated": true }
  }
}

為什麼大多數 API 不是真正的 RESTful？

實際考量：

• 工具生態系統 — OpenAPI 等規範提供了立即可用的好處，如自動產生文件和用戶端程式碼
• 開發體驗 — 靜態合約比動態超媒體更容易理解和實作
• 團隊耦合 — 同一團隊開發前後端時，解耦的必要性不明顯
• 學習曲線 — 建構真正的超媒體驅動用戶端需要更多的認知負擔
• 效能考量 — 額外的連結資訊可能增加回應大小
• 缺乏標準化工具 — 相比 OpenAPI，HATEOAS 缺乏成熟的工具支援

現實中的權衡：

// 典型的「RESTful」API（實際上是 HTTP-based RPC）
GET /api/users/123
POST /api/users/123/activate
DELETE /api/users/123

// 真正的 RESTful API 會是
GET /api/users/123
{
  "id": 123,
  "name": "John Doe",
  "status": "inactive",
  "_links": {
    "self": { "href": "/users/123" },
    "activate": { "href": "/users/123/activate", "method": "POST" },
    "delete": { "href": "/users/123", "method": "DELETE" }
  }
}