API 團隊之間越來越流行標準化他們的 API 設計流程。對許多人來說，標準化 API 設計的努力始於內部演練，以確保參與設計、開發和測試 API 的每個人都在同一頁面上。
設計指南可能會以 PDF 格式或在內部 Wiki 上發布，供大家參考，並制定流程以確保團隊遵循設計指南。但是，許多公司更進一步，公開發布這些指南，作為開發人員使用其 API 的參考，以及任何想從他們的經驗中學習的人的參考。Arnaud Lauret（更廣為人知的名稱為API Handyman）是API Stylebook 的創作者，這是一個線上資源，致力於透過學習有效實施標準化 API 設計流程的組織，協助 API 開發人員解決其 API 設計挑戰。Arnaud 審查了來自各行各業的組織的風格指南，包括 Cisco、Google、Paypal、Microsoft 等，並將他的發現彙整到一個易於瀏覽的資源中。
我最近有機會與 Arnaud 談談 API Stylebook 的由來，並就組織開始建立自己的 API 設計指南的旅程給予建議。正如 Arnaud 所解釋的，建立內部風格指南只是這個過程的開始。請閱讀我們下面的完整採訪，以了解接下來會發生什麼，以及 Arnaud 從他在 API Stylebook 上的工作中學到的經驗。
是什麼啟發您建立 API Stylebook 作為 API 設計人員的資源？
我建立 API Stylebook 是因為我花了很多時間才找到 基本 API 設計問題的解決方案，而且我認為我可能不是唯一一個。當我開始設計 REST API 時，我的許多基本 API 設計問題都不容易解決。很難找到有關面臨類似挑戰的人們如何解決這些問題的資訊。有時我沒有找到任何問題的答案。而且我不知道設計 API 時必須考慮的所有事項。
憑藉經驗，我找到了自己的答案，這些答案有時很好，有時很糟糕。我也意識到我遺漏了一些重要的方面。除了必須忍受某些設計錯誤之外，最讓我困擾的是這些錯誤在業界如此普遍，以至於不應該有人犯這些錯誤。這些問題已經被解決過很多次，以至於不應該有人再浪費時間解決這些問題。我希望做些事情來幫助人們不要犯同樣的錯誤並浪費時間。這就是 API Stylebook 的開始。那時我意識到，越來越多的公司和公共組織正在分享他們設計 API 的方式，公開他們的指南。所有這些指南都包含常見 API 設計問題的答案。
我開始收集它們，目標只是提供連結清單。但是當我閱讀它們時，我意識到僅提供連結清單可能無法真正幫助設計人員快速找到解決方案。由於它們彼此之間的組織或使用的詞彙都非常不同，因此找到解決方案仍然可能是一個真正的負擔。因此，我決定列出這些指南涵蓋的所有主題，並將它們正規化，以便快速直接地存取它們。因此，API Stylebook 就誕生了。
您如何選擇 API Stylebook 上涵蓋的設計指南？在評估風格指南時，您會尋找哪些特定標準？
可能有無數的部落格文章在談論 API 設計，但我只想提供在現實世界情境中被驗證過的資料。這就是為什麼我只將公司真正使用的「官方 API 設計指南」新增到 API Stylebook 的原因。
您認為為什麼越來越多的公司專注於標準化他們的 API 設計？
公司建立指南最明顯的原因是，在組織中開發的 API 越多，就越需要它們彼此保持一致。提供具有共同行為、模式和標準外觀的 API 將大大簡化想要使用它們的人員（無論他們是否來自公司）的工作。另一個原因也可能是 API 設計的效率。有了指南，API 設計人員可以專注於真正重要的事項，而不是浪費時間無休止地討論細微的細節或試圖解決公司內部已經解決過的設計問題。
我知道您已經說過並撰寫了很多關於 OpenAPI 的文章。您是否看到公司將 OpenAPI 等標準納入其 API 設計指南中？
IMHO 不夠多 :-) 我只在 API Stylebook 上發現了兩個 (Haufe 和 Zalando)。但是Zalando 絕對是如何使用 OpenAPI 的最佳範例。他們在設計階段使用 OpenAPI 規格，將其儲存在版本控制系統中，並使用名為 Zally 的自訂工具控制 API 設計。這真是太棒了！我們需要更多關於 OpenAPI 和設計控制的工具。Zalando 也提供了一些關於如何使用 OpenAPI 規格準確描述資料的提示。
我們看到經常出現的兩個主題是管理和版本控制。您如何看待組織在其 API 風格指南中處理管理？
管理涵蓋許多主題，從我們為什麼要製作 API 到它們應該如何設計以及如何處理其生命週期。API 設計指南可能涵蓋其中一些主題，但並非全部。我分析過的指南中，除了版本控制之外的管理主題並沒有很好的代表性。它們主要關注如何設計 API，而不是其餘的。但仍然有一些指南談論棄用（Zalando 或 Atlassian）或 API 設計驗證流程（Haufe）。我認為應該在一個或多個其他文件中描述管理指南，以避免混淆太多不同的問題。
版本控制，這絕對是一個管理主題，並且與設計緊密相關，在指南中更為常見。它通常透過如何呼叫特定版本的 API 來呈現。有多種策略，例如使用 URL 或內容協商。但是，如果您不知道您所做的變更是否具有破壞性，那麼了解如何區分 API 的兩個版本是沒有意義的，只有少數指南提供有關此方面的資訊。
Google 提供了一些提示，但 Zalando 再次是關於這個主題最完整的指南
對於正在開始實施 API 風格指南的組織，您從研究中學到了哪些其他建議或經驗？
不要認為一旦您編寫了指南，工作就完成了。指南必須不斷發展，因為它們一開始不會涵蓋所有可能的問題。最重要的是，如果不推廣它們並控制所做的事情，就沒有人會閱讀或尊重它們。如果您想了解更多關於 API 設計指南的來龍去脈，您應該參加 APIStrat 並參加我的會議 API 設計之王。
感謝您的閱讀！想尋找更多 API 資源嗎？訂閱 Swagger 電子報。您將每月收到包含我們精選 API 文章、培訓課程、教學以及其他資訊的電子郵件。訂閱