附錄 A：API 設計工作表#

這些工作表用來配合我們的實務設計建議。它們可以搭配第五章的虛構範例使用，也可以作為你自己 API 設計的可重複使用模板。

定義商業目標#

問題陳述#

簡要定義問題，以及它如何影響客戶和業務。

影響描述#

定義你的 API 的成功是什麼樣子。發布新 API 之後，世界會有什麼不同？

關鍵使用者故事#

使用以下模板列出你的 API 的幾個關鍵使用者故事（User Stories）：

As a [使用者類型], I want [動作] so that [預期結果].

  1. __________________________
  2. __________________________
  3. __________________________
  4. __________________________
  5. __________________________

技術架構#

描述你所選擇的技術架構，以及做出此決定的原因。你可以加入圖表來展示你考慮過的各範式的優缺點。

以下是一個可選的範例表格：

考慮的模式、範式或協定優點缺點是否選用？

API 規格模板#

標題#

__________________________

作者#

__________________________

問題#

__________________________

解決方案#

__________________________

實作#

提供實作計畫的高層次描述。你可以使用額外的表格或圖表來描述你的計畫。

認證#

描述開發者將如何獲取 API 的存取權限。

其他考量#

如果你考慮過其他 API 範式、架構、認證策略、協定等，簡要說明你曾考慮過的選項。

輸入與輸出（REST、RPC）#

如果你正在設計 REST 或 RPC API，描述端點（endpoints）、輸入和輸出。你可以新增欄位或使用不同的表格格式來描述請求和回應。

URI輸入（Inputs）輸出（Outputs）

事件與酬載（事件驅動 API）#

如果你正在設計事件驅動 API（Event-Driven API），描述事件及其酬載（payloads）。你可以新增欄位來記錄額外資訊，例如 OAuth scope。

事件（Events）酬載（Payload）

錯誤#

HTTP 狀態碼錯誤代碼（Error Code）詳細錯誤訊息（Verbose Error）描述（Description）

回饋計畫#

描述你計畫如何收集對 API 設計的回饋，包括是否計畫向 beta 測試者發布。

API 實作檢查清單#

  • 定義要解決的具體開發者問題
  • 撰寫內部 API 規格
  • 取得對 API 規格的內部回饋
  • 建構 API
    • 認證（Authentication）
    • 授權（Authorization）
    • 錯誤處理（Error Handling）
    • 速率限制（Rate-limiting）
    • 分頁（Pagination）
    • 監控與日誌記錄（Monitoring and Logging）
  • 撰寫文件
  • 與合作夥伴進行新 API 的 beta 測試
  • 收集 beta 合作夥伴的回饋並進行修改
  • 建立通知開發者變更的溝通計畫
  • 發布 API 變更
Backward 結論