RESTful API-設計規範

URL 設計

動詞+賓語

RESTful 的核心思想就是，客戶端發出的數據+操作指令都是“動詞+賓語”的結構，比如GET /articles這個命令，GET 是動詞，/articles 是賓語，動詞通常就有 5 種 HTTP 請求方法，對應 CRUD 操作，根據 HTTP 規範，動詞一律大寫。

# GET：讀取（Read）
# POST：新建（Create）
# PUT：替換（Replace），全量更新，應具冪等性
# PATCH：更新（Update），通常是部分更新
# DELETE：刪除（Delete）

動詞的覆蓋

有些客戶端只能使用 GET 和 POST 這兩種方法。服務器必須接受 POST 模擬其他三個方法（PUT、PATCH、DELETE）。這時，客戶端發出的 HTTP 請求，要加上X-HTTP-Method-Override屬性，告訴服務器應該使用哪一個動詞，覆蓋 POST 方法。

POST /api/Person/4 HTTP/1.1
X-HTTP-Method-Override: PUT

上面代碼中，X-HTTP-Method-Override 指定本次請求的方法是 PUT，而不是 POST。

賓語必須是名詞

賓語就是 API 的 URL，是 HTTP 動詞作用的對象。它應該是名詞，不能是動詞。比如，/articles 這個 URL 就是正確的，而下面的 URL 不是名詞，所以都是錯誤的。

# /getAllCars
# /createNewCar
# /deleteAllRedCars

複數 URL

既然 URL 是名詞，那麼應該使用複數，還是單數？這沒有統一的規定，但是常見的操作是讀取一個集合，比如 GET /articles（讀取所有文章），這裡明顯應該是複數。

Note ⇒ 為了統一起見，建議都使用複數 URL，比如 GET /articles/2 要好於 GET /article/2。

避免多級 URL

常見的情況是，資源需要多級分類，因此很容易寫出多級的 URL，比如獲取某個作者的某一類文章。

# GET /authors/12/categories/2

這種 URL 不利於擴展，語義也不明確，往往要想一會，才能明白含義。

更好的做法是，除了第一級，其他級別都用查詢字符串表達。

# GET /authors/12?categories=2  //good

下面是另一個例子，查詢已發布的文章。你可能會設計成下面的 URL。

# GET /articles/published

查詢字符串的寫法明顯更好

# GET /articles?published=true  //good

URL 命名一致性

為降低歧義、提高可讀性與可維護性，建議遵循以下慣例（參考 REST API URI Naming）：

使用斜線 / 表示層級關係：如 /device-management/managed-devices/{id}。
結尾不要加斜線：路徑最後一個字元不應為 /，例如用 /articles 而非 /articles/。
使用連字號 - 提高可讀性：如 /device-management，避免使用底線 _（在部分字型或螢幕上易被遮蔽）。
使用小寫：URI 路徑建議一律小寫，避免大小寫差異造成快取或比對問題。
不要使用副檔名：格式由 Content-Type 表頭表達，不在 URI 加 .json 或 .xml。

# Good
GET /device-management/managed-devices?region=USA&sort=installation-date

# Avoid
GET /device-management/managed_devices/
GET /articles/list.json

資源類型：集合與單例

集合（collection）：用複數名詞，如 /users、/orders，代表一組資源。
單例（document）：集合下的單一資源，如 /users/{id}、/users/admin。
子集合：若需表達從屬關係，可為 /customers/{id}/orders，但層級不宜過深；Microsoft 建議不超過 collection/item/collection，更深時可改為查詢參數或回應內連結（HATEOAS）。見 Web API Design - Azure。

查詢、分頁與篩選

集合類 API 應支援查詢參數，避免為每種條件開新 API（參考 Microsoft - API Design）：

分頁：limit（每頁筆數）、offset（起始位置），並設定 limit 上限以防濫用。
篩選：用查詢參數表達條件，如 GET /orders?status=shipped&minCost=100。
排序：如 sort=price 或 sort=-createdAt（依實作約定）。
欄位選擇：如 fields=id,name，讓客戶端只取所需欄位，減少 payload。

GET /orders?limit=25&offset=50
GET /orders?status=shipped&sort=createdAt
GET /orders?fields=id,status,amount

狀態碼

狀態碼必須精確

這好有 document 來說明文 status Overview of Status Codes

客戶端的每一次請求，服務器都必須給出回應。回應包括 HTTP 狀態碼和數據兩部分。

[HTTP 狀態碼]

1xx：相關信息
2xx：操作成功
3xx：重定 (redirect)
4xx：客戶端錯誤
5xx：服務器錯誤

這五大類總共包含 100 多種狀態碼，覆蓋了絕大部分可能遇到的情況。每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需查看狀態碼，就可以判斷出發生了什麼情況，所以服務器應該返回盡可能精確的狀態碼。

API 不需要 1xx 狀態碼，下面介紹其他四類狀態碼的精確含義。

2XX 狀態碼

200 狀態碼表示操作成功，但是不同的方法可以返回更精確的狀態碼。

# GET: 200 OK
# POST: 201 Created
# PUT: 200 OK
# PATCH: 200 OK
# DELETE: 204 No Content  //已經不存在

PUT 應具冪等性：同一請求重送多次，資源狀態一致。POST、PATCH 不保證冪等。
PATCH 用於部分更新，body 可為 JSON Merge Patch 或 JSON Patch（RFC 7396 / RFC 6902）；伺服器若不支援請求的 patch 格式，應回 415 Unsupported Media Type。
POST 建立資源時，由伺服器決定新資源 URI 並在回應 Location 回傳；客戶端不應自行指定新資源路徑。

此外，202 Accepted 表示請求已接受、尚未處理完成，常用於非同步操作。回應應在 Location 表頭或 body 提供狀態查詢 URL，讓客戶端輪詢；完成後該端點可回 303 See Other 並在 Location 指向新資源。見 Microsoft - Asynchronous methods。

HTTP/1.1 202 Accepted
Location: /api/status/12345

# 客戶端 GET 上述 URL 可得到：
# { "status": "In progress", "links": [{ "rel": "cancel", "method": "DELETE", "href": "/api/status/12345" }] }
# 完成後可回 303 See Other，Location: /api/orders/12345

3xx 狀態碼

3xx 狀態碼表示重定向（redirect），主要有下面幾種。

301 目標網頁移到新網址(永久轉址)。
302 暫時轉址
304 已讀取過的圖片或網頁，由瀏覽器緩存 (cache) 中讀取。

API 用不到 301 狀態碼（永久重定向）和 302 狀態碼（暫時重定向，307 也是這個含義），因為它們可以由應用級別返回，瀏覽器會直接跳轉，API 級別可以不考慮這兩種情況。

API 用到的 3xx 狀態碼，主要是 303 See Other，表示參考另一個 URL。它與 302 和 307 的含義一樣，也是"暫時重定向"，區別在於 302 和 307 用於 GET 請求，而 303 用於 POST、PUT 和 DELETE 請求。收到 303 以後，瀏覽器不會自動跳轉，而會讓用戶自己決定下一步怎麼辦。

下面是一個例子。

HTTP/1.1 303 See Other
Location: /api/orders/12345

4xx 狀態碼

4xx 狀態碼表示客戶端錯誤，主要有下面幾種。

400 Bad Request：服務器不理解客戶端的請求，未做任何處理。
401 Unauthorized：用戶未提供身份驗證憑據，或者沒有通過身份驗證。
403 Forbidden：用戶通過了身份驗證，但是拒絕執行它。
404 Not Found：所請求的資源不存在，或不可用。
405 Method Not Allowed：用戶已經通過身份驗證，但是所用的 HTTP 方法不在他的權限之內。
408 Client Request timeout，請求超時。
409 Conflict：請求的資源已經存在，或者請求的資源與請求的資源衝突。
410 Gone：所請求的資源已從這個地址轉移，不再可用。
411 沒有指定 content-length，使用 POST 傳送參數時，必須指定參數的總長度
414 URL 太長導致伺服器拒絕處理。
415 Unsupported Media Type：客戶端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式。
422 Unprocessable Entity ：客戶端上傳的附件無法處理，導致請求失敗。
429 Too Many Requests：客戶端的請求次數超過限額。

5xx 狀態碼

5xx 狀態碼表示服務端錯誤。一般來說，API 不會向用戶透露服務器的詳細信息，所以只要兩個狀態碼就夠了。

500 Internal Server Error：客戶端請求有效，服務器處理時發生了意外。
503 Service Unavailable：服務器無法處理請求，一般用於網站維護狀態。
505 不支此 HTTP 版本

服務器回應

不要純文本

API 返回的數據格式，不應該是純文本，而應該是一個 JSON 對象，因為這樣才能返回標準的結構化數據。所以，服務器回應的 HTTP 頭的 Content-Type 屬性要設為 application/json。

客戶端請求時，也要明確告訴服務器，可以接受 JSON 格式，即請求的 HTTP 頭的 ACCEPT 屬性也要設成 application/json。下面是一個例子。

GET /orders/2 HTTP/1.1
Accept: application/json

發生錯誤時，不要返回 200 狀態碼

有一種不恰當的做法是，即使發生錯誤，也返回 200 狀態碼，把錯誤信息放在數據體裡面，就像下面這樣。

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

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

上面代碼中，解析數據體以後，才能得知操作失敗。

這種做法實際上取消了狀態碼，這是完全不可取的。正確的做法是，狀態碼反映發生的錯誤，具體的錯誤信息放在數據體裡面返回。下面是一個例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payload.",
  "detail": {
     "surname": "This field is required."
  }
}

提供鏈接

API 的使用者未必知道，URL 是怎麼設計的。一個解決方法就是，在回應中，給出相關鏈接，便於下一步操作。這樣的話，用戶只要記住一個 URL，就可以發現其他的 URL。這種方法叫做 HATEOAS。

舉例來說，GitHub 的 API 都在 api.github.com 都這個域名。訪問它，就可以得到其他 URL。

{
  ...
  "feeds_url": "<https://api.github.com/feeds>",
  "followers_url": "<https://api.github.com/user/followers>",
  "following_url": "<https://api.github.com/user/following{/target}>",
  "gists_url": "<https://api.github.com/gists{/gist_id}>",
  "hub_url": "<https://api.github.com/hub>",
  ...
}

上面的回應中，挑一個 URL 訪問，又可以得到別的 URL。對於用戶來說，不需要記住 URL 設計，只要從 http://api.github.com 一步步查找就可以了。

HATEOAS 的格式沒有統一規定，上面例子中，GitHub 將它們與其他屬性放在一起。更好的做法應該是，將相關鏈接與其他屬性分開。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "In progress",
   "links": [
    { "rel": "cancel", "method": "DELETE", "href": "/api/status/12345" },
    { "rel": "edit", "method": "PUT", "href": "/api/status/12345" }
  ]
}

API 版本控制

當 schema 或行為有破壞性變更時，需透過版本讓舊客戶端仍可運作。常見做法（Microsoft - Versioning）：

方式	範例	優點	注意
URI 版本	`/v2/customers/3`	簡單、易快取	同一資源有多個 URI，HATEOAS 連結需帶版本
Query 版本	`/customers/3?version=2`	同一資源單一 URI	部分舊代理不快取帶 query 的請求
Header 版本	`Custom-Header: api-version=2`	URI 不變	快取需能區分 header，否則易錯用
Media type 版本	`Accept: application/vnd.contoso.v1+json`	與 HATEOAS 相容	需解析 Accept，快取策略較複雜

info

HATEOAS（Hypermedia as the Engine of Application State，超媒體即應用狀態引擎）是 REST 的一項約束：回應內容中要帶超媒體連結，讓客戶端能從回應裡「發現」下一步可用的動作與資源位址，而不是事先寫死 URL。

好處：伺服端可變更 URI 而不破壞客戶端；客戶端只需知道入口，其餘依 rel、href 等連結探索。
實務：常見做法是在 JSON 裡加 _links 或 links，列出 rel（關係）、href（URL）、必要時 method，如上方的「超媒體與連結」範例。版本控制若用 Media type 版本（如 Accept: application/vnd.api.v2+json），可與 HATEOAS 相容，因連結由伺服端產生，自然帶正確版本。

Richardson 成熟度模型（RMM）

Leonard Richardson 以四級描述 API 與 REST 的貼合程度：

Level 0：單一 URI，所有操作都用 POST（如傳統 RPC/SOAP）。
Level 1：依資源分拆 URI，但操作仍可能集中在少數動詞。
Level 2：正確使用 HTTP 方法（GET/POST/PUT/PATCH/DELETE）與狀態碼，多數對外 API 落在此級。
Level 3：具備超媒體（HATEOAS），回應含連結與可執行動作，客戶端可依連結探索 API。

Level 3 最貼近 Fielding 所定義的 REST。

URL 設計​

動詞+賓語​

動詞的覆蓋​

賓語必須是名詞​

複數 URL​

避免多級 URL​

URL 命名一致性​

資源類型：集合與單例​

查詢、分頁與篩選​

狀態碼​

狀態碼必須精確​

2XX 狀態碼​

3xx 狀態碼​

4xx 狀態碼​

5xx 狀態碼​

服務器回應​

不要純文本​

發生錯誤時，不要返回 200 狀態碼​

提供鏈接​

API 版本控制​

Richardson 成熟度模型（RMM）​

參考資料​