[ADP-50] API 景觀

review phase 1

本文需要更多的參考資料。

概述

API 景觀指的是組織內所有 API 相關措施集合構成的總體風景。

整體架構

分類和分層：根據功能和用途對 API 進行分類，如核心業務 API、數據 API 和第三方整合 API。使用分層架構，如表現層、業務邏輯層和數據訪問層。
依賴管理：確保 API 之間的依賴關係明確且最小化。使用 API 網關或服務網格來管理依賴關係。
API 網關：使用 API 網關進行統一的流量管理，處理身份驗證、授權、速率限制和日誌記錄。

版本管理

版本策略：建立清晰的版本策略，包括主要版本、次要版本和修補版本。使用 URL 路徑或請求標頭來識別版本。
棄用計劃：定義 API 的棄用流程和時間表，並將此資訊傳達給用戶以便遷移。

一致性

命名約定：確保所有 API 的命名一致，包括資源名稱、操作和參數。
錯誤處理：使用統一的錯誤格式和錯誤代碼。參考 RFC 9457 進行問題詳細定義。
數據格式：除非有特定需求需要替代格式，否則將 JSON 標準化為主要數據格式。

身份驗證和授權

統一身份驗證：對所有 API 使用一致的身份驗證機制，如 OAuth 2.0 或 JWT。
細粒度授權：實施基於角色或屬性的細粒度授權策略來控制訪問。

文件和發現

自動文件生成：使用 OpenAPI 或 GraphQL Schema 等工具自動生成 API 文件。
API 目錄：維護統一的 API 目錄，以便開發人員發現和訪問。

性能和監控

性能測試：定期進行性能測試，確保 API 回應時間和吞吐量符合標準。
監控和警報：實施監控和警報系統，以跟踪 API 性能和運營指標。

安全性

數據保護：使用 HTTPS 確保數據傳輸過程中的加密。
速率限制：實施速率限制以防止濫用和 DDoS 攻擊。
安全審計：定期進行安全審計以識別和修復漏洞。

測試和部署

自動化測試：利用 CI/CD 管道進行自動化測試，包括單元測試、集成測試和端到端測試。
藍綠部署：採用藍綠部署策略，確保新 API 版本的平滑過渡和回滾能力。

協作和治理

開發流程：建立包括設計審查、代碼審查和測試驗收的開發流程。
治理委員會：設立 API 治理委員會，負責制定標準和確保合規。

API 開放性和集成

開放 API：促進 API 開放性，支持第三方開發者進行集成和創新。
集成策略：制定明確的集成策略，涵蓋第三方 API 的使用和內部 API 的互操作性。