作者 | Jason Harmon
譯者 | 馬可薇
策劃 | 丁曉昀
摘要：
- 在 API 團隊中定義統一的語言和術語，以保障一致性並避免後續混亂
- 應用共享風格指南和提示規則，以實現更好的管理和標準化
- 儘早建立 API 設計審查團隊，將所有利益相關者均納入考量範圍，而不是僅僅覆蓋技術領域利益相關者
- 建立一個能真實反映組織中 API 範圍和深度的 API 分類，以提高可發現性和可見性
- 儘可能地最大限度使用共享組件和模型，幫助開發人員輕鬆進行擴展和復用
對大規模的 API 設計而言，一致性是需要花些功夫才能實現的。API 的胡亂堆砌和正經平台的主要區別就在於一致性。而在這種語境下，一致性僅僅意味著多個 API 中命名規則、分頁等交互模式、授權機制等因素的統一性。
一般來說，評審委員會如果在人們以為工作已經完成後才延遲發現問題，將會給 API 開發者們帶來心理創傷。更糟的則是委員會的設計取而代之，從而導致進度拖慢，或者開發者們為求免遭痛苦而想盡辦法避開這一過程。
若想完全解鎖現代平台，去中心化的治理是更易於伸縮和參與的方式。這種方式僅需要在每個領域或功能區都安排一位接受過標準和整體架構訓練的專題專家，為 API 開發者們提供良好的引導。
了解這一背景後，讓我們來進一步分析 API 的設計評審要如何開展，流程如何制定，如何讓組織做好準備，從而避免拖長的時間表和匱乏的開發者參與感。
下文中將列出部分能確保這一過程順利的關鍵先決條件。
定義一致的語言或術語
API 的使用是一項極為精鍊的體驗，因此語言在其中的影響相較於其他多數設計領域而言，所占據的比例要高得離譜。團隊中對不同術語的定義和描述可能會因人而異，其表現形式便是 API 團隊的混亂和生產力的下降。
雖然 API 門戶或文檔是良好開發者體驗的必需品，但設計優秀的 API 應在無需這二者的情況下便能清晰表述大部分內容。消費者如果熟悉某個術語，且交互模式明顯，那麼這段體驗將會是快速且無痛的。一致性是 API 的堆疊和真正的平台在體驗上的主要區別。
從共通的語言開始，建立 API 的計劃和治理流程。雖然這樣乍一看並不現實，但為平台定義一個以客戶為中心的共享詞彙或語法是至關重要的，這將是組織的整體加速器。許多術語可能在公司內部都有不同的涵義，再加上終端用戶甚至大多都不認識這些術語。
提前做好這些功課可以避免在 API 設計的過程中因命名而產生衝突。與相關的利益相關者一同定義每個領域中的共通術語，確保 API 設計的廣泛使用和了解。確定了內部術語的標準化後，別忘了檢查其是否也符合外部的需求。通過使用客戶語言和以客戶為中心的 API 開發視角，可幫助團隊避免因為使用客戶不熟悉的技術術語而帶來混亂，為此，請確保內部理解和外部理解的同步。
定義共享組件
API 的消費者在面對 API 之間不同的模型或參數時，可能會遭遇一段困惑、沮喪且耗時頗長的過程。舉例來說，一個使用聯繫信息的 API 與同平台下另一個 API 使用了完全不同的模型，消費者將被迫去處理這二者之間的差異。更糟糕的是，處理數據的系統性差異將會進一步擴大，從而造成功能性上的差異。
儘早確定共用的組件（模型、參數、頭，等等）和支持其的系統，通過在 API 定義中將共享組件相連，可確保後續對這些組件的修改可輕鬆在推廣至全平台，減輕 API 消費者所不必要的認知負擔。
所使用的共用組件越多，提升一致性、可復用性，以及後續合作和效率提升的機會便越高。開發者們都喜歡不走回頭路的「DRY（Don』t Repeat Yourself） 方法」。共享組件越多，創新也越容易，人們不需要一次又一次地從頭開始，重複同樣的事情。共享組件還可讓團隊更迅速地擴展，更輕鬆地培訓 API 團隊之外的新開發者或利益相關者。
應用共享的風格指南和提示規則
多數簡單的命名規則、交互模式，以及認證機制，都能提供風格指南的自動化，並提早標記出不一致之處。
首個風格指南是於 2013 至 2015 年間制定的，為 API 的開發團隊定下了外觀和體感（又稱 DX）的期望值。一致性的設計需求在 API 平台開發之初就很明顯了，在 Paypal（當年作者也是這個團隊的一員！）和 Heroku 的早期共同努力下，第一批成功項目的設計指南得到公開分享。
雖然能用於協助風格指南的自動化工具有很多，但開源工具 Spectral 已成為定義 API 提示規則集的標準。先對路徑、參數等約定俗稱的規則進行調整，定義自動提示規則，從而避免因糾結「正確」的規則而帶來的衝突。規則一經探討和確定，就儘量不要再反覆討論這個問題，讓錯誤的提示消失就好了。
至於無法自動化的設計標準，應將其記錄並使其便於 API 設計者獲得。通過培訓解釋自動化和人工驗證規則的重要性，可以為開發者建立全心全意支持這項舉措的動力，避免意外和摩擦的發生。
在組織上下設立 API 設計審查員
雖然應設置一個 API 啟用的團隊負責策劃這些設計標準並促進社區的發展，但也應在每個功能區或領域中啟用權威。
API 標準固然重要，但系統約束、特定客戶需求、組織優劣勢等領域知識，最好還是由該領域內的專家來處理。如果指望著集中化的 API 啟用團隊成員了解公司的一切，那麼交付延遲和開發人員脫離這些瓶頸幾乎註定是會發生的。
培訓課程可以成為傳播 API 標準重要性的有利技術。此外，人們往往會找到合適的中小企業提供管理權限。尋找那些對 API 表現出熱情、對一致性和標準相關性的知識，且在技術上能得到其他同行或上級尊重的人們（作者常稱其為「叛逆者」）。
成功的 API 開發會涉及組織內的許多人，這些人往往具備截然不同的技能，有的人會構建和部署 API，有的人則能在商業問題的戰略層面確定 API 的價值。在探討設計審查需要牽涉的人員時，別忘了商業利益相關者。通常情況下，僅關注技術方面可能會導致後續的失敗。視角越廣越好！
確保組合或 API 分類的一致性
平台內部的產品經理應在 API 組合或目錄的整體構成上達成一致。分類有許多不同的形式，它們能對 API 進行整理，讓人們在無需清楚明白自己目標的情況下，更輕鬆地找到自己要找的；也允許潛在用戶按功能或其他用戶的關注分類瀏覽可用 API。
好的分類應具備搜索和過濾功能，允許開發者輕鬆縮小選擇範圍；也應為分類中的每個 API 提供可對比、可接受的細節，讓人有清晰的前進路線。
儘早通過用例和基本命名的功能性概述，對任何新推出的 API 進行審查，以確保語言的一致性、可復用性，以及新 API 與大平台整體的「契合度」。
啟用團隊中的產品經理負責組合的調整過程，團隊成員則應各自負責一個可管理的領域集合。至少也要為特定領域的產品經理提供一個定期討論的場所。
乍一看之下似乎要做很多事，但別忘了，API 的標準應該通過疊代而發展。隨著 API 不斷被設計，我們會意識到其中完善標準的機會。認識到這點後，我們應確保在前期的準備工作中覆蓋基本知識，並確保 API 主管清晰地認知到要如何提出和採用對標準的修改。
實施 API 設計審查
在達成上述的先決條件後，API 設計審核也就基本完成了。對領域驅動的中小企業而言，設計審查通常可被整合到進行中的設計工作內。如果審查能在早期便於平台相磨合，設計審查人員則能更自信該 API 與大局相吻合。此外，如果 API 設計者在疊代過程中發現了錯誤的提示，那麼除了對開發者培訓相關提示性規則，以及簡單解決提示性錯誤外，不應再有關於約定俗成規則的討論。
不是所有東西都能被自動化，有時產品和架構需求會發生衝突。在手動執行管理檢查、驗證客戶語言（這點很難被自動化），以及確定最終一致性之後，再進行 API 設計審查。確立這個時間線後，就不再需要會議時間了，異步的探討往往便足以。
更重要的是密切關注 API 設計審查的周期。隨著時間的推移，更多去中心化的中小企業將對現有標準和新標準的採用更加熟悉，API 設計審查頻率也應明顯地下降。
原文連結：
API Design Reviews Are Dead. Long Live API Design Reviews!（ https://www.infoq.com/articles/api-design-review/）
對話用友王文京，探尋企業數智化的「密鑰」
Electron末日來了？又一應用將其拋棄！WhatsApp強制推行原生應用：速度更快、內存占用更少
獨家對話金蝶李帆：企業級PaaS平台將如何引領企業的科技創新？
紅帽對 RHEL 下游造成毀滅性打擊！停止公開企業版原始碼，要擠占開源份額實現盈利？