作者 | Jason Harmon

譯者 | 馬可薇

(資料圖片僅供參考)

策劃 | 丁曉昀

對大規(guī)模的 API 設(shè)計而言，一致性是需要花些功夫才能實現(xiàn)的。API 的胡亂堆砌和正經(jīng)平臺的主要區(qū)別就在于一致性。而在這種語境下，一致性僅僅意味著多個 API 中命名規(guī)則、分頁等交互模式、授權(quán)機制等因素的統(tǒng)一性。

一般來說，評審委員會如果在人們以為工作已經(jīng)完成后才延遲發(fā)現(xiàn)問題，將會給 API 開發(fā)者們帶來心理創(chuàng)傷。更糟的則是委員會的設(shè)計取而代之，從而導(dǎo)致進度拖慢，或者開發(fā)者們?yōu)榍竺庠馔纯喽氡M辦法避開這一過程。

若想完全解鎖現(xiàn)代平臺，去中心化的治理是更易于伸縮和參與的方式。這種方式僅需要在每個領(lǐng)域或功能區(qū)都安排一位接受過標(biāo)準(zhǔn)和整體架構(gòu)訓(xùn)練的專題專家，為 API 開發(fā)者們提供良好的引導(dǎo)。

更為重要的是，在大部分開發(fā)工作完成之前便確定 API 設(shè)計，可以在很大程度上避免在最后一刻才發(fā)現(xiàn)問題，從而影響交付時間（通常被稱作是設(shè)計優(yōu)先方法）。通過 OpenAPI（HTTP/"REST" API 的事實標(biāo)準(zhǔn)）等規(guī)格格式，可在所有的開發(fā)工作開始之前便定義 API，從而更早地進行調(diào)整并識別問題。

了解這一背景后，讓我們來進一步分析 API 的設(shè)計評審要如何開展，流程如何制定，如何讓組織做好準(zhǔn)備，從而避免拖長的時間表和匱乏的開發(fā)者參與感。

下文中將列出部分能確保這一過程順利的關(guān)鍵先決條件。

API 的使用是一項極為精煉的體驗，因此語言在其中的影響相較于其他多數(shù)設(shè)計領(lǐng)域而言，所占據(jù)的比例要高得離譜。團隊中對不同術(shù)語的定義和描述可能會因人而異，其表現(xiàn)形式便是 API 團隊的混亂和生產(chǎn)力的下降。

雖然 API 門戶或文檔是良好開發(fā)者體驗的必需品，但設(shè)計優(yōu)秀的 API 應(yīng)在無需這二者的情況下便能清晰表述大部分內(nèi)容。消費者如果熟悉某個術(shù)語，且交互模式明顯，那么這段體驗將會是快速且無痛的。一致性是 API 的堆疊和真正的平臺在體驗上的主要區(qū)別。

從共通的語言開始，建立 API 的計劃和治理流程。雖然這樣乍一看并不現(xiàn)實，但為平臺定義一個以客戶為中心的共享詞匯或語法是至關(guān)重要的，這將是組織的整體加速器。許多術(shù)語可能在公司內(nèi)部都有不同的涵義，再加上終端用戶甚至大多都不認(rèn)識這些術(shù)語。

提前做好這些功課可以避免在 API 設(shè)計的過程中因命名而產(chǎn)生沖突。與相關(guān)的利益相關(guān)者一同定義每個領(lǐng)域中的共通術(shù)語，確保 API 設(shè)計的廣泛使用和了解。確定了內(nèi)部術(shù)語的標(biāo)準(zhǔn)化后，別忘了檢查其是否也符合外部的需求。通過使用客戶語言和以客戶為中心的 API 開發(fā)視角，可幫助團隊避免因為使用客戶不熟悉的技術(shù)術(shù)語而帶來混亂，為此，請確保內(nèi)部理解和外部理解的同步。

API 的消費者在面對 API 之間不同的模型或參數(shù)時，可能會遭遇一段困惑、沮喪且耗時頗長的過程。舉例來說，一個使用聯(lián)系信息的 API 與同平臺下另一個 API 使用了完全不同的模型，消費者將被迫去處理這二者之間的差異。更糟糕的是，處理數(shù)據(jù)的系統(tǒng)性差異將會進一步擴大，從而造成功能性上的差異。

盡早確定共用的組件（模型、參數(shù)、頭，等等）和支持其的系統(tǒng)，通過在 API 定義中將共享組件相連，可確保后續(xù)對這些組件的修改可輕松在推廣至全平臺，減輕 API 消費者所不必要的認(rèn)知負擔(dān)。

所使用的共用組件越多，提升一致性、可復(fù)用性，以及后續(xù)合作和效率提升的機會便越高。開發(fā)者們都喜歡不走回頭路的“DRY（Don’t Repeat Yourself） 方法”。共享組件越多，創(chuàng)新也越容易，人們不需要一次又一次地從頭開始，重復(fù)同樣的事情。共享組件還可讓團隊更迅速地擴展，更輕松地培訓(xùn) API 團隊之外的新開發(fā)者或利益相關(guān)者。

多數(shù)簡單的命名規(guī)則、交互模式，以及認(rèn)證機制，都能提供風(fēng)格指南的自動化，并提早標(biāo)記出不一致之處。

首個風(fēng)格指南是于 2013 至 2015 年間制定的，為 API 的開發(fā)團隊定下了外觀和體感（又稱 DX）的期望值。一致性的設(shè)計需求在 API 平臺開發(fā)之初就很明顯了，在 Paypal（當(dāng)年作者也是這個團隊的一員?。┖?Heroku 的早期共同努力下，第一批成功項目的設(shè)計指南得到公開分享。

雖然能用于協(xié)助風(fēng)格指南的自動化工具有很多，但開源工具 Spectral 已成為定義 API 提示規(guī)則集的標(biāo)準(zhǔn)。先對路徑、參數(shù)等約定俗稱的規(guī)則進行調(diào)整，定義自動提示規(guī)則，從而避免因糾結(jié)“正確”的規(guī)則而帶來的沖突。規(guī)則一經(jīng)探討和確定，就盡量不要再反復(fù)討論這個問題，讓錯誤的提示消失就好了。

至于無法自動化的設(shè)計標(biāo)準(zhǔn)，應(yīng)將其記錄并使其便于 API 設(shè)計者獲得。通過培訓(xùn)解釋自動化和人工驗證規(guī)則的重要性，可以為開發(fā)者建立全心全意支持這項舉措的動力，避免意外和摩擦的發(fā)生。

雖然應(yīng)設(shè)置一個 API 啟用的團隊負責(zé)策劃這些設(shè)計標(biāo)準(zhǔn)并促進社區(qū)的發(fā)展，但也應(yīng)在每個功能區(qū)或領(lǐng)域中啟用權(quán)威。

API 標(biāo)準(zhǔn)固然重要，但系統(tǒng)約束、特定客戶需求、組織優(yōu)劣勢等領(lǐng)域知識，最好還是由該領(lǐng)域內(nèi)的專家來處理。如果指望著集中化的 API 啟用團隊成員了解公司的一切，那么交付延遲和開發(fā)人員脫離這些瓶頸幾乎注定是會發(fā)生的。

培訓(xùn)課程可以成為傳播 API 標(biāo)準(zhǔn)重要性的有利技術(shù)。此外，人們往往會找到合適的中小企業(yè)提供管理權(quán)限。尋找那些對 API 表現(xiàn)出熱情、對一致性和標(biāo)準(zhǔn)相關(guān)性的知識，且在技術(shù)上能得到其他同行或上級尊重的人們（作者常稱其為“叛逆者”）。

成功的 API 開發(fā)會涉及組織內(nèi)的許多人，這些人往往具備截然不同的技能，有的人會構(gòu)建和部署 API，有的人則能在商業(yè)問題的戰(zhàn)略層面確定 API 的價值。在探討設(shè)計審查需要牽涉的人員時，別忘了商業(yè)利益相關(guān)者。通常情況下，僅關(guān)注技術(shù)方面可能會導(dǎo)致后續(xù)的失敗。視角越廣越好！

平臺內(nèi)部的產(chǎn)品經(jīng)理應(yīng)在 API 組合或目錄的整體構(gòu)成上達成一致。分類有許多不同的形式，它們能對 API 進行整理，讓人們在無需清楚明白自己目標(biāo)的情況下，更輕松地找到自己要找的；也允許潛在用戶按功能或其他用戶的關(guān)注分類瀏覽可用 API。

好的分類應(yīng)具備搜索和過濾功能，允許開發(fā)者輕松縮小選擇范圍；也應(yīng)為分類中的每個 API 提供可對比、可接受的細節(jié)，讓人有清晰的前進路線。

盡早通過用例和基本命名的功能性概述，對任何新推出的 API 進行審查，以確保語言的一致性、可復(fù)用性，以及新 API 與大平臺整體的“契合度”。

啟用團隊中的產(chǎn)品經(jīng)理負責(zé)組合的調(diào)整過程，團隊成員則應(yīng)各自負責(zé)一個可管理的領(lǐng)域集合。至少也要為特定領(lǐng)域的產(chǎn)品經(jīng)理提供一個定期討論的場所。

乍一看之下似乎要做很多事，但別忘了，API 的標(biāo)準(zhǔn)應(yīng)該通過迭代而發(fā)展。隨著 API 不斷被設(shè)計，我們會意識到其中完善標(biāo)準(zhǔn)的機會。認(rèn)識到這點后，我們應(yīng)確保在前期的準(zhǔn)備工作中覆蓋基本知識，并確保 API 主管清晰地認(rèn)知到要如何提出和采用對標(biāo)準(zhǔn)的修改。

在達成上述的先決條件后，API 設(shè)計審核也就基本完成了。對領(lǐng)域驅(qū)動的中小企業(yè)而言，設(shè)計審查通?？杀徽系竭M行中的設(shè)計工作內(nèi)。如果審查能在早期便于平臺相磨合，設(shè)計審查人員則能更自信該 API 與大局相吻合。此外，如果 API 設(shè)計者在迭代過程中發(fā)現(xiàn)了錯誤的提示，那么除了對開發(fā)者培訓(xùn)相關(guān)提示性規(guī)則，以及簡單解決提示性錯誤外，不應(yīng)再有關(guān)于約定俗成規(guī)則的討論。

不是所有東西都能被自動化，有時產(chǎn)品和架構(gòu)需求會發(fā)生沖突。在手動執(zhí)行管理檢查、驗證客戶語言（這點很難被自動化），以及確定最終一致性之后，再進行 API 設(shè)計審查。確立這個時間線后，就不再需要會議時間了，異步的探討往往便足以。

更重要的是密切關(guān)注 API 設(shè)計審查的周期。隨著時間的推移，更多去中心化的中小企業(yè)將對現(xiàn)有標(biāo)準(zhǔn)和新標(biāo)準(zhǔn)的采用更加熟悉，API 設(shè)計審查頻率也應(yīng)明顯地下降。

/articles/api-design-review/

關(guān)鍵詞：