[ADP-48] API 健壯性

reviewing phase 1

這篇文章需要更多實際內容。

概述

API 健壯性指的是 API 能夠處理各種輸入和使用場景而不會失敗的能力。在設計 API 時，一個關鍵考慮因素是是否採用嚴格或寬鬆的方法來進行輸入驗證、錯誤處理和整體設計理念。本文討論了這兩種方法的優缺點，並提供了示例來說明每種方法。

指導

• 在同一應用程序中應該(SHOULD)保持 API 健壯性決策的一致性。

嚴格(robust)的 API 指南

定義

嚴格的 API 強制執行嚴格的驗證並遵守定義的標準。每個請求都必須精確符合預期格式,任何偏差都會導致錯誤。

優點

1. 一致性: 確保所有輸入都標準化，減少意外行為的風險。
2. 安全性: 通過嚴格驗證所有輸入來最小化漏洞，防止格式錯誤的請求和潛在攻擊。
3. 可預測性: 客戶端可以依賴明確定義的契約，使集成和調試更容易。

缺點

1. 僵硬性: 可能對微小偏差不太寬容，可能導致客戶端的錯誤率更高。
2. 複雜性: 需要詳細的文件和廣泛的驗證邏輯，增加了開發和維護工作。

示例

考慮一個用於創建用戶配置的 API，具有以下嚴格要求:

• 端點: POST /users

• 負載:

  {
      "username": "字符串 (字母數字, 3-20 個字符)",
      "email": "字符串 (有效的電子郵件格式)",
      "age": "整數 (18-100)"
  }

任何不符合這些標準的請求都會導致 400 Bad Request 回應，並附帶詳細的錯誤消息:

{
  "type": "https://example.com/problems/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "'username' 屬性(property)必須是字母數字且長度在 3 到 20 個字符之間。"
}

寬鬆(loose)的 API 指南

定義

寬鬆的 API 允許更大的靈活性，並容忍預期輸入格式的偏差，通常實現默認值或寬恕小錯誤。

優點

1. 靈活性: 適應更廣泛的輸入，減少客戶端錯誤的可能性。
2. 易用性: 簡化了客戶端的集成，因為小錯誤不太可能導致錯誤。
3. 用戶體驗: 通過優雅地處理小問題，提供更流暢的用戶體驗。

缺點

1. 不一致性: 可能導致輸入格式的變化，使 API 不太可預測。
2. 安全風險: 更寬容的輸入驗證可能使 API 暴露於安全漏洞。
3. 處理複雜性: 需要強大的錯誤處理和默認機制，實現起來可能很複雜。

示例

考慮同一用戶配置創建 API 的寬鬆方法:

• 端點: POST /users

• 負載:

  {
      "username": "字符串 (可選)",
      "email": "字符串 (可選, 有效的電子郵件格式)",
      "age": "整數 (可選, 默認為 18)"
  }

如果客戶端省略了 username 或 email 屬性(property)，API 仍會創建用戶配置，在必要時分配默認值:

{
  "id": "12345",
  "username": "defaultUser",
  "email": "user@example.com",
  "age": 18
}

平衡嚴格性和寬鬆性

最佳實踐

1. 關鍵屬性(property): 對影響核心功能或安全性的關鍵屬性(property)應用嚴格驗證，如身份驗證令牌或財務數據。
2. 可選屬性(property): 允許對可選屬性(property)寬鬆處理，在適當的情況下提供默認值或推斷值。
3. 錯誤處理: 實施全面的錯誤處理和日誌記錄，以監控和解決可能由寬鬆輸入引起的潛在問題。
4. 文件: 清楚地記錄預期的輸入格式、驗證規則和任何寬鬆行為，以指導客戶端正確使用 API。

示例

用戶配置創建的平衡方法可能涉及對 email 屬性(property)進行嚴格驗證，並對 username 和 age 屬性(property)進行寬鬆處理:

• 端點: POST /users

• 負載:

  {
      "username": "字符串 (可選, 字母數字, 3-20 個字符)",
      "email": "字符串 (必填, 有效的電子郵件格式)",
      "age": "整數 (可選, 默認為 18)"
  }

回應將反映嚴格和寬鬆處理的組合:

• 嚴格錯誤:

  {
      "type": "https://example.com/problems/invalid-input",
      "title": "無效輸入",
      "status": 400,
      "detail": "'email' 屬性(property)必須是有效的電子郵件格式。"
  }

• 寬鬆處理:

  {
      "id": "12345",
      "username": "defaultUser",
      "email": "user@example.com",
      "age": 18
  }