由于性能是成功的關鍵指標，并且導出引擎經過了翻新，我們希望逐步全面地測試我們的系統。我們首先在 UI 中添加了一個新的導出選項（如果出現問題，客戶可以禁用該選項）以開始產生流量。為了幫助我們識別極端情況，我們將導出指向“最全面、符合標準和最新的機器可讀 API 定義目錄”（可在此處獲得： https:?//github.com/APIs-guru/openapi-directory），并對原始文檔和我們的新導出運行了頻譜。在許多情況下，我們發現使用新導出時驗證錯誤的數量顯著減少。在大多數情況下，這是清理 x-examples 和其他從 OAS2.0 更改為 OAS3.X 的屬性的結果。

便于使用

由于我們客戶的目標是提取完整且有效的定義文件（OAS 和 JSON Schema）并將其集成到下游工具中，因此 Catalog API 需要提供完全獨立的“捆綁”導出，無需外部引用或依賴項。Catalog API 不是簡單地內聯取消引用 $refs，而是創建可重復使用的“組件”（適用于 OAS3.X）或“定義”（適用于 OAS2）。這保留了各種工具（例如 SDK 生成）中使用的重要參數和模型名稱。

（左側為原始組件庫參考，右側為捆綁導出）

與 API 身份驗證和版本控制類似，還有一些其他“基礎”設計決策：

• 標準化錯誤模型– 我們采用了RFC7807。但是，我了解到，最好為不同的錯誤情況創建不同的模型，即使它們具有相同的屬性，因為這些模型將由 SDK 生成器使用。
• 速率限制– 保護您自己的系統并為您的客戶提供限制自身速率所需的信息。常用的 x-rate-limit、x-rate-limit-remaining 和 x-rate-limit-reset 可以完成這項工作。
• 請求標識符– 您、您的支持團隊和工程師都會感激簡單的 Stoplight-Request-Id響應標頭所提供的附加上下文。將此標識符包含在所有相關日志中，并培訓您的客戶將其包含在您的支持請求中，以使調試變得輕而易舉。

在設計階段，您可能會花費最多時間充實端點。由于 Stoplight 本身是圍繞項目及其內容組織的，因此我們首先將 /projects/ 作為主要資源。指定分支（對于 Web 項目，也稱為“版本”）或提交是必要的子資源，最后使用 /export/ 命令，后跟要導出的目標的文件路徑。可選地，有一個 include_internal 查詢字符串參數，它將包含或排除標有 x-internal 的對象（默認為 true）。我們相信最終結果直觀且易于緩存。

（圖片來自Catalog API 網絡研討會）

原文鏈接：Designing the Catalog API: How Stoplight Thinks About Public APIs