譯自：API Governance: Using Patterns From PayPal, Netflix and More[1]作者：Charles Humble

許多組織將API治理交給機會，但這是一種冒險的做法。相反，看看全球企業如何指導他們的API開發。

我承認，API 治理并不是一個令人心跳加速的話題。它或許最好被描述為枯燥但重要。

做好 API 治理，有助于保持一致性并促進 API 的重用。它還應該提供一種機制，讓內部和外部客戶都能提供反饋并請求更改。然后，可以根據其他競爭性優先事項評估這些請求，以便就是否、如何以及何時實施它們做出決策。

根據我的經驗，許多組織將 API 治理[2] 交給機會。但是，與組織文化一樣，無論你是否定義治理流程，它都會出現。因此，在我看來，最好是有意為之。

治理不必繁瑣。許多開發人員都歡迎有關如何設計 API 的指南，因為這意味著不必過多地擔心做出選擇——例如如何處理一組 API 結果中的分頁，或者事務 ID 應該叫什么。

INNOQ 的首席顧問、O'Reilly 作者和 API 建議 YouTuber Erik Wilde[3] 告訴 The New Stack：“在最近德國的一次會議上，我問了 150 名開發人員，‘你們有多少人在組織中擁有 API 指南？’，只有很少的人舉手。”“然后我問，‘你們有多少人希望擁有指南？’，看起來大多數人都舉手了。我沒有預料到差異會如此之大。”

如果你想為組織中的 API 建立治理流程，你可以應用三種主要模式：集中式設計權限、聯邦式治理和受影響的自治理。每種模式都有不同的權衡，并且更適合某些情況。

在本文中，借助現實世界的例子，我們將研究每一種模式，并檢查它最適合應用于何處。

模式 1：集中式設計權限

集中式設計權限 (CDA) 帶有架構審查委員會和過于官僚的流程的包袱，或許是我們考慮的三種模式中最不受歡迎的一種。但這不應該讓你忽視這樣一個事實：在某些情況下，它可能是有效的。

例如，它是發展編程語言的一種廣泛采用的方法——想想 C++ 的 ISO 標準[4]、Java 的 Java 社區流程[5] 或 Python 增強提案 (PEP)[6] 流程以及相應的 Python 指導委員會。

CDA 的主要作用是看門人，這意味著為了有效，它需要防止做出低質量或有風險的決策。除了其看門人的作用外，該機構還應驗證良好的決策，并通過 文檔[7] 和其他指導來告知團隊如何滿足質量要求。

投資高質量文檔尤其重要；如果沒有它，實施團隊需要與 CDA 舉行的會議數量會迅速膨脹到無法管理的程度。

由于 CDA 的主要作用是看門人，因此其成功在很大程度上受到組織內技術團隊文化的的影響。如果各個團隊覺得可以忽略 CDA 告訴他們做的事情，那么它就無法有效。相反，CDA 需要認識到，過于繁重或官僚的流程會促使開發人員尋求繞過它的方法。

使用 CDA 模式的主要優點是它推動了統一性。使用此模式可以避免或至少限制開發人員擁有更多自主權時可能發生的重復工作量。它還可以確保正確遵循安全策略和其他組織協議。

一個重要的缺點是，隨著公司的發展，該機構幾乎不可避免地會成為瓶頸，導致 API 項目停滯不前，因為其成員等待與核心團隊討論問題。

Wilde 建議：“使用此模型，你通常會遇到可擴展性問題，開發人員認為設計權限阻礙了他們的工作。”“這與其說他們不喜歡該機構正在做什么，不如說他們認為這會減慢他們的速度，因此他們試圖繞過它來完成工作。”與其他形式的軟件架構權威一樣，API 設計權威成員也存在與實際工作脫節而無法做出良好決策的風險。這種現象等同于Stack Overflow的共同創建者Joel Spolsky[8]所說的“架構宇航員[9]”。

鑒于此，CDA模式最好應用于啟動流程時，或變更量相對較小時。不出所料，它在監管更嚴格的行業中通常更受歡迎。

PayPal如何使用集中式設計權威

在線支付提供商PayPal使用集中式設計權威進行治理。在2018年北歐API平臺峰會上發言[10]時，當時擔任該支付提供商API平臺負責人的Jayadeba Jena[11]描述了一個四步流程：

1. 定義（API組合對齊）：將包含用例和目標客戶的API提案提交給API組合團隊。組合團隊審查重疊部分，并就API分類法、命名空間和資源名稱提供建議。如果批準，則建立一個GitHub代碼庫來定義API契約，然后可以開始設計階段。

2. 設計（API設計審查）：對于REST API，使用OpenAPI[12]方法，將API契約和示例通過拉取請求提交給中心團隊進行審查。一群API設計師會審查規范是否符合設計標準。解決問題和意見，然后，一旦API規范獲得批準，它就進入開發階段。

3. 開發（API實現）：實現符合標準的API，例如服務等級協議和日志記錄。這是一個迭代過程，會來回提交PR。在這個過程結束時，團隊使用工具根據OpenAPI規范自動創建驗證測試，來驗證實現是否與契約定義匹配。

4. 外部化（商家和合作伙伴訪問）：提供速率限制、API外觀和OAuth范圍。創建外部文檔。更新SDK。確保API通過集成就緒檢查清單。

為了保持一致性，確保遵守公司的安全策略、向后兼容性和生命周期管理。PayPal的CDA維護著一套定義模式、版本控制策略和樣式指南的標準。這確保了“客戶/合作伙伴獲得統一的視圖和相同的API體驗，”Jena說。

Jena指出，CDA最終成為瓶頸。PayPal的解決方案是培訓產品負責人根據組織范圍的治理標準來審查其開發團隊的工作。中央API設計團隊仍然負責制定治理標準，但它不再負責審查每個API。

模式2：聯邦治理

我們的第二個模式，聯邦治理，是一種內部咨詢模型。來自集中專家池的個人會加入負責構建API的團隊。這些專家可以就關鍵決策提供建議，也可以被授權代表實施團隊做出決策。

如果人員配備適當，聯邦治理團隊應該有足夠的帶寬來進行研究，嘗試各種方案，并就實踐、工具和框架提出有根據的建議。

聯邦治理比CDA模式具有三個優勢。首先，由于中心團隊專家的參與，可以在流程早期做出重要決策。

其次，專家們自己可以獲得經驗，并將這些經驗帶回中心團隊，確保理解和指導不斷改進。第三，那些監督工作的人不太可能成為與現實脫節的“宇航員”，因為他們直接參與了這個過程。

然而，聯邦治理是資源密集型的，因為需要大量的專家來確保每個團隊都能得到所需的幫助。與咨詢公司一樣，您必須要么增加員工數量以滿足高峰需求，并接受團隊成員在空閑時期可能沒有太多工作要做，要么您需要準備好裁員以應對工作量下降——或者接受一些瓶頸。

實際上，我還發現，需要付出相當大的努力才能保持專家之間對共享理解的一致性，以避免失去一致性。

HSBC如何使用聯邦治理

匯豐銀行從集中式團隊轉向了聯邦治理。“我們已經建立了一個由匯豐銀行各部門的‘API 冠軍’組成的社區，以了解標準，將其應用于各自的團隊，并升級問題或差距，”匯豐銀行批發銀行首席API架構師John Phenix在其公司博客文章中寫道。

然而，匯豐銀行也遇到了一些問題。Phenix 寫道：“并非所有 API 冠軍都擁有同等的經驗，因此我們仍然需要一個相當大的中央團隊來確保一致性。”該公司的解決方案是提高自動化程度。

他補充道：“自動化測試可以構成DevOps流水線的一部分，確保測試內置于常規的構建、測試和發布周期中。”“這阻止了人們試圖操縱治理流程，并確保了更高的API審查覆蓋率。”

但Phenix 承認，并非所有檢查都能以這種方式自動化：“只需相對較小的投資，就可以在一致性、完整性和可觀測性方面獲得巨大的收益。”

模式 3：定向自我治理

也許最流行的API治理方法是定向自我治理，這是一種依賴影響而非控制的模式。這種模式最適合DevOps和云原生軟件構建方法。因此，它已被Netflix等硅谷公司推廣，并被Spotify等歐洲同行效仿。

總體目標是允許高度的自主性，但在這種自主性內，要保持一些護欄——一條“黃金路徑”——這使得開發人員更容易做正確的事情。

Wilde告訴我們：“我們越來越多地看到平臺的建立以及API治理的融入。”“您可以使用自動化進行CI/CD流水線中的一些設計檢查，以使流程盡可能輕量級。”

借鑒“團隊拓撲”一書，可以將自我治理與支持團隊相結合，這些團隊可以幫助處理流對齊團隊不擅長的方面，例如API設計。

Wilde 告訴TNS：“你需要提高組織內部發生的事情的有效性和標準化，而不要過于強硬。”“目的是避免團隊多次做同樣的事情，或者不同的團隊選擇不同的解決方案。”

這種方法相對于我們已經討論過的其他兩種方法的一個顯著優勢是執行速度；當團隊被賦予對其做出的決策的完全自主權時，他們可以非常快速地行動。它還可以很好地擴展，而無需大量額外招聘。

主要缺點是團隊可能會無意中做出不一致的決策，或者為了局部環境而優化決策，從而損害整體利益。“對于內部API，如果它們遵循相同的外觀和感覺，這確實有助于提高開發人員的生產力，因為您的開發人員將使用許多不同的API，”Wilde 告訴The New Stack。“這使得制定指南成為一項不錯的投資，因為您將在開發人員生產力方面獲得回報。”

英國金融時報如何使用定向自我治理

在英國金融時報任職期間，Sarah Wells擔任過許多高級職務，其中包括媒體內容平臺的團隊負責人，該平臺為內部和外部合作伙伴提供對英國金融時報內容的豐富版本的API訪問。

從Wells的回憶來看，英國金融時報在自我治理方面的方法似乎相當有機。“我們沒有API專家團隊，”她告訴The New Stack。“但我們確實有API網關和一些文檔標準。”

Wells說：“我們還有一些關于健康檢查外觀的標準，有了這些，我們發現我們的開發人員更有可能使他們的API看起來像一個通用的API。”“我們討論了構建API時需要考慮什么，以確保它與所有其他API完全不同；這非常有價值。例如，我們試圖確保它可以通過API網關發現，并且我們在命名方式上保持一致。”

Netflix 如何結合 API 治理策略

正如我們所看到的，即使在同一家公司內，也可以結合不同的方法。并且在不同的地方和不同的時間使用多種方法通常是最佳的。

例如，Netflix以提倡高信任、高自主性的文化而聞名，它使用黃金路徑和定向自我治理方法。然而，這家流媒體公司正在更廣泛地采用GraphQL的過程中，也使用了集中式治理。2021年，Netflix的高級軟件工程師在InfoQ播客與我交談[13]時，解釋了該公司如何擁有一個模式工作組來監督圖的演變。

“這是一個非常依賴人員的過程，”她說。“任何想要成為這個聯邦圖一部分的團隊都需要參與模式工作組。我們有一位數據架構師負責監督這個單一統一圖的演變。因此，任何時候有人想要向現有類型添加新的實體或字段，他們都必須來到模式工作組參與討論。

“我們確保這一切都說得通，而且大家不會隨意地向圖中添加模式片段。”

最后，無論您選擇哪種方法，請記住，治理，就像您的API一樣，應該隨著時間的推移而發展。持續考慮您的治理模型是否正在做您想做的事情非常重要。

引用鏈接

[1]API Governance: Using Patterns From PayPal, Netflix and More:https://thenewstack.io/api-governance-using-patterns-from-paypal-netflix-and-more/

[2]API 治理:https://thenewstack.io/api-management/

[3]Erik Wilde:https://www.youtube.com/ErikWilde

[4]C++ 的 ISO 標準:https://thenewstack.io/coming-to-iso-c-26-standard-an-ai-acceleration-edge/

[5]Java 的 Java 社區流程:https://thenewstack.io/microsoft-goes-deep-on-java-with-jcp-membership/

[6]Python 增強提案 (PEP):https://thenewstack.io/guido-van-rossums-ambitious-plans-for-improving-python-performance/

[7]文檔:https://thenewstack.io/poor-documentation-is-costly-heres-how-to-fix-it/

[8]Joel Spolsky:https://www.linkedin.com/in/joelspolsky/

[9]架構宇航員:https://www.joelonsoftware.com/2001/04/21/dont-let-architecture-astronauts-scare-you/

[10]在2018年北歐API平臺峰會上發言:https://www.youtube.com/watch?v=LuZiWas_nNw

[11]Jayadeba Jena:https://www.linkedin.com/in/jayadeba-jena-1a6a0020/

[12]OpenAPI:https://www.openapis.org

[13]與我交談:https://www.infoq.cn/podcasts/netflix-graphql-adoption-performance/