2024-10-09 restAPI設計標準

發表於 分類於 閱讀次數：
2024-10-09 restAPI設計標準

REST（Representational State Transfer）是一種常用的軟體架構風格，專門用來設計基於網絡的應用程序（通常是 Web API）。REST API 的設計標準包括一些最佳實踐和原則，用來確保 API 的結構清晰、一致、易於使用和擴展。以下是 REST API 設計中的核心標準和最佳實踐：

1. 使用 HTTP 方法

REST API 基於 HTTP 協議，因此需要遵循 HTTP 方法來表達不同的操作，這有助於使 API 更符合 HTTP 協議的語義。

  • GET：用於查詢資源。只讀操作，應該是無副作用的。
    • 例如：GET /api/packages 查詢所有包裹。
  • POST：用於創建資源。一般會創建一個新的資源並返回其詳細信息。
    • 例如：POST /api/packages 創建一個新的包裹。
  • PUT：用於更新資源。替換或更新現有的資源。
    • 例如：PUT /api/packages/123 更新包裹 123 的信息。
  • PATCH：用於部分更新資源。只更新資源的部分屬性。
    • 例如：PATCH /api/packages/123 部分更新包裹 123。
  • DELETE：用於刪除資源。
    • 例如：DELETE /api/packages/123 刪除包裹 123。

2. 資源的標識與命名（URI）

在 REST API 中，資源是通過 URI（Uniform Resource Identifier）來標識的。設計好的 URI 是清晰、可理解的，並且表達了資源的含義。

  • URI 結構：
    • 資源應使用名詞來表示，而不是動詞。例如，使用 /packages 而不是 /getPackages。
    • 資源標識應遵循層級結構。例如，包裹的項目可能是 /packages/123/items。
  • 良好的 URI 設計例子：
    • GET /api/users：獲取所有用戶。
    • GET /api/users/42：獲取用戶 ID 為 42 的詳細信息。
    • POST /api/users：創建一個新用戶。
    • PUT /api/users/42：更新用戶 42。

3. 使用合適的 HTTP 狀態碼

在 REST API 中，應用程序狀態是通過 HTTP 狀態碼來表示的。使用正確的 HTTP 狀態碼可以提高 API 的可用性和可讀性。

  • 200 OK：請求成功，一般用於 GET、PUT、DELETE 等操作。
  • 201 Created：資源創建成功，一般用於 POST 操作。
  • 204 No Content：操作成功，但沒有需要返回的內容，一般用於 DELETE 操作。
  • 400 Bad Request：請求無效，當請求參數錯誤時使用。
  • 401 Unauthorized：未經授權，當請求需要身份驗證時使用。
  • 403 Forbidden：已經授權，但沒有操作許可權。
  • 404 Not Found：找不到資源，當請求的資源不存在時使用。
  • 500 Internal Server Error：服務器錯誤，當服務器內部發生錯誤時使用。

4. 返回統一的數據格式（通常是 JSON）

  • JSON 作為首選格式：大多數 REST API 使用 JSON 作為數據格式，因為它輕量且易於解析和讀取。
  • 返回一致的結構：返回的數據應該保持一致的格式，這樣客戶端可以更容易地解析和使用。通常應包括狀態、消息、數據等，例如：
    1
    2
    3
    4
    5
    6
    7
    8
    {
      "status": "success",
      "data": {
        "id": 123,
        "name": "Package 1",
        "status": "In Transit"
      }
    }

5. 版本控制

版本控制可以避免接口的突然更改影響到用戶，特別是在需要進行 API 更新時。

  • 在 URI 中添加版本號：
    • 例如：/api/v1/packages 或 /v2/users。這樣可以確保向後兼容。
  • 通過標頭版本控制（較少見，但也是可選方式）：
    • 可以通過自定義的 HTTP 標頭來傳遞版本信息，例如 Accept: application/vnd.myapi.v1+json。

6. HATEOAS（Hypermedia as the Engine of Application State）

  • HATEOAS 原則：這是一種為 API 客戶端提供可導航鏈接的方式，這些鏈接幫助客戶端了解可用的下一步操作。
  • 例子：
    • 在返回包裹信息時，還可以返回可導航的鏈接：
      1
      2
      3
      4
      5
      6
      7
      8
      {
        "trackingNumber": "12345",
        "status": "In Transit",
        "_links": {
          "self": { "href": "/api/packages/12345" },
          "cancel": { "href": "/api/packages/12345/cancel" }
        }
      }
    • HATEOAS 的主要優勢在於增加了 API 的自描述性，讓客戶端知道應用程序的下一步操作。

7. 遵循 REST 的無狀態性

  • 無狀態性：每個請求應該包含所有必要的信息，以便服務器能夠理解並處理請求。服務器不應該保存客戶端的狀態。
  • 好處：這樣的設計提高了系統的可伸縮性，因為每個請求可以獨立處理，而不需要了解前一個請求的上下文。

8. 使用合適的錯誤處理與錯誤消息

  • 在發生錯誤時，應返回有意義的錯誤信息，幫助用戶了解發生了什麼。
  • 例子：
    1
    2
    3
    4
    5
    6
    7
    {
      "type": "https://example.com/errors/invalid-data",
      "title": "Invalid data provided",
      "status": 400,
      "detail": "The provided 'trackingNumber' is invalid.",
      "instance": "/api/packages/123"
    }
  • 提供錯誤細節：應包括 status（狀態碼）、detail（具體錯誤描述）等字段。

9. 安全性考慮

  • 身份驗證：可以使用 OAuth2 或 JWT（JSON Web Token） 進行身份驗證。
  • 授權控制：使用授權策略，確保只有合適的用戶可以訪問某些資源。
  • HTTPS：所有的 API 請求應該通過 HTTPS 發送，以防止數據在傳輸過程中被竊取。

小結

  • 使用適當的 HTTP 方法和狀態碼，保持語義化。
  • URI 應該清晰且簡潔，代表資源。
  • 返回統一的數據格式（通常是 JSON），保持數據結構一致。
  • 使用版本控制 來管理 API 的演化。
  • 遵循 REST 的無狀態性原則，每個請求應該是獨立的。
  • 實施安全措施，如身份驗證和 HTTPS。

這些設計標準和最佳實踐可以幫助您創建一個清晰、一致、易於使用的 REST API。如果還有其他問題，隨時問我！