[ADP-42] API 生命週期管理

縱覽

API 生命週期管理涉及幾個階段：

1. 設計：定義 API 的目的、功能和結構。
2. 開發：實現 API 的功能。
3. 測試：確保 API 按預期工作並滿足性能要求。
4. 發佈：釋出 API 並使其可供使用。
5. 廢棄：將 API 標記為廢棄並計劃其退役。
6. 退役：完全移除 API。

API 預覽

在 API 生命週期的前三個階段，它被分類為 API 預覽。

API 預覽提供了收集反饋的寶貴機會，在正式發佈之前，使開發團隊能夠識別潛在問題並進行必要的調整。

• 您可以(MAY)發佈處於預覽狀態的 API 文件，前提是它被正確標記。
  • 您應該(SHOULD)使用 x-api-state: preview 或在您的 OpenAPI 文件中包含預覽標籤，以明確指示 API 的預覽狀態。
• 客戶必須(MUST)知道，處於預覽中的 API 可能：
  • 不完整
  • 缺乏穩定性（在向後相容性方面）
  • 不適合生產使用（即使它在生產 API 文件網站上有展示）

API 版控

• 必須選擇最適合您的 API 和用戶需求的策略。無論您選擇哪種方法，請在文件中清楚解釋您的版本控制策略。請參見 API 版本控制

API 退役

• 如果 API 的受眾大於 COMPANY_INTERNAL，您必須在 API 被廢棄時通過以下標頭通知客戶：Deprecation 和 Sunset。
  • 您應該使用 Deprecation 標頭來通知 API 處於廢棄狀態，並在 OpenAPI 文件中設置為廢棄。請參見 HTTP Headers - Deprecation 和 OpenAPI Operation: Deprecation
  • 您應該使用 Sunset 標頭來指示請求的 API 將於何時變得不可用。請參見 Sunset

  INFO

  COMPANY_INTERNAL以下指的是僅在公司內部使用的 API，並未對外部客戶公開。更多詳情，請參見 API 受眾。

• 一個 API 在退役之前首先進入廢棄狀態，然後是 Sunset 狀態，最後是最終退役。
• 同時使用這兩個標頭是可能的，並且通常是推薦的。

處理依賴客戶

在廢棄 API 時：

• 及早並經常與 API 消費者溝通。
• 提供清晰的遷移路徑到更新版本或替代 API。
• 提供支持和文件以協助過渡。
• 考慮在合理的時間內維持舊版本，以便客戶遷移。

最佳實踐

• 設計時考慮未來，允許擴展性。
• 使用語義版本控制以清晰傳達變更。
• 在整個 API 生命週期中保持全面的文件。
• 根據使用指標和反饋定期審查和更新 API。
• 自動化盡可能多的生命週期管理，包括測試和部署。
• 實施監控和日誌記錄，以快速識別和解決問題。
• 為 API 消費者提供沙盒環境，以安全地測試和集成。
• 建立明確的服務水平協議(SLA)並確保遵守。
• 定期與 API 消費者溝通以收集反饋並了解他們的需求。
• 考慮實施 API 管理平台，以簡化整個生命週期的管理。

相關 ADP

• Sunset
• Deprecation

參考

• Deprecation Header Draft
• RFC 8594 - The Sunset HTTP Header Field
• RESTful API 設計最佳實踐
• API 版本控制方法
• 演變中的 HTTP API
• API 生命週期管理影片