改變遊戲規則的 API 設計審查的5個技巧

谷歌有一個 API 問題。正如他們在 2016 年的論文“大規模 API 設計審查”中所述，在過去十年中，生產的 API 數量大幅增長。大量的不一致和可用性問題也是如此。沒有一個問題是罪魁禍首。

為了解決這個問題，谷歌建立了一個輕量級、可擴充套件的分散式設計審查流程。同行評審長期以來一直是健康的現代軟體開發實踐的主要內容。谷歌在 API 設計方法中的應用最終減少了可用性缺陷，同時比 API 可用性測試更有效。

各種規模的公司，不僅僅是世界上的谷歌，都可以從 API 設計審查過程中受益。但是涉及到什麼？

1. 不同的視角加強了 API 設計審查

首先，API 設計審查不是程式碼審查。相反，設計審查是關於評估服務介面的直觀性、完整性和一致性。談話是關於利用許多人的專業知識和才能。通過這種對話，出現了更強大、更耐用和更一致的設計。

在這次談話中，API 生產團隊應該對問題有最大的瞭解。這種親密關係對於確保正確表示各種子系統的操作和執行時期望至關重要。

一些額外的審閱者可能會從新使用者的角度來看待 API，提供一組全新的視角，類似於新整合商體驗 API 的方式。其他審閱者可能在許多 API 上積累了豐富的經驗，提供了與開發團隊的深度相匹配的廣泛的 API 知識。

2. API 審查從 API 描述開始

在我們分享資訊之前，我們必須說同一種語言。通過服務介面傳達的業務意圖也是如此。在請求和響應 API 中，API 提供的功能可以在寫入OpenAPI 規範 (OAS)的描述中捕獲。查詢 API，如使用 GraphQL 的 API，可以使用 SDL 文件。或者，表達方式可能是 Postman Collection，一種能夠捕獲端點有效負載和操作資訊的開源格式。類似地，更多實時 API 可能會使用AsyncAPI描述來描述它們的介面。

無論選擇何種規範，以標準化表示形式捕獲 API 的獨特操作都可以實現對話。一致的、機器可解析的描述也解鎖了自動化工具。利用 linting 之類的自動化進行重要但無差別的語法爭論，可以騰出寶貴的時間來討論更主觀的領域，例如 API-product fit。

隨著時間的推移，這個 API 定義變成了一個活生生的工件，記錄了知識的積累和測試過程中的假設。在設計審查之後，該工件將作為未來客戶 API 文件的基礎。

3. 預定義的樣式指南支援設計審查

一些設計問題可能沒有明顯的“正確”答案。這種模糊性會導致大型API 生態系統中的不一致和可用性問題。API 風格指南為這些設計問題提供了建議的（有時是必需的）解決方案集合。

幾乎所有采用 API 設計審查的公司都會有一套標準，他們將根據這些標準進行審查。這些 API 風格指南應該易於發現、理解和實施。此外，任何風格指南都應該包含一個明確的過程，說明貢獻者如何隨著時間的推移修改和發展內容。

風格指南內容解決的問題應該與公司尋求在 API 生態系統中推動的結果相關。結果可能包括在以下方面實現更大的一致性：

• 身份驗證方法
• URI 和引數命名約定
• 錯誤處理
• 版本控制
• 有效載荷結構和格式
• 過濾
• 連結和分頁

雖然需要這些領域，但 API 設計審查還應不僅評估 API 的形式，還評估其功能。深入瞭解 API 需要存在的原因以及如何最好地表達其業務價值很難在標準文件中量化。但是，針對這些方面採取額外的努力可能會對最終設計產生相當大的積極影響。

4. API 設計審查的執行情況各不相同

執行設計評審的機制應有所不同，以適應組織內現有的流程和規範。稽核可以非同步執行，例如在原始碼控制、公司 CMS 或共享文件中交換評論。然而，根據我的經驗，這些場景在個體貢獻者靈活性方面獲得了什麼，但它們缺乏細微差別和後續參與。很少有人會在他們的日程安排中尋求更多的會議。但是，將必要的利益相關者“現場”聚集在一起可以實現更高程度的交流。這將大大減少所有相關人員的後續澄清和挫敗感。

不管審查是如何進行的，一個關鍵的考慮因素必須是 API 的預期分發範圍：

• API 是隻有直接開發團隊知道的內部元件嗎？
• 或者 API 會在業務部門內使用嗎？
• API 是否會保留在組織防火牆內，但會成為整個組織使用的關鍵基礎設施？
• 或者我們是否必須擴大潛在使用者以包括更大世界的使用者，或者因為他們是明確的供應商，或者是沒有限制的任何第三方？

您對這些問題的回答可能會顯著影響 API 設計審查的性質。您的組織可能會決定，在直接實施團隊之外暴露有限的 API（例如微服務）可能根本不需要審查。

5. 反饋應該是雙向的

一個健康的設計審查過程並不是單向的資訊傳播，從審查者流向被審查者。相反，API初稿中的遺漏或疏忽為設計審查人員提供了第一手的、可操作的資訊。這種訊號應該成為公司的流程、標準和工具的後續修正的基礎。

還有其他更正式的方法來評估不斷變化的API開發團隊的偏好、胃口和成熟度。然而，就額外的時間或精力而言，很少有比在現有的對話中應用同理心傾聽更自由的。熟練的評審員會像說話一樣傾聽，找出哪些方法是有效的，哪些是無效的，以及可能出現的培訓需求的模式。