PagerDuty的API開發經驗分享 – Increment

banq發表於2021-08-06
APIREM

在本文中，將分享PagerDuty如何透過很少的新軟體開發和一些簡單的流程更改來啟動的API 開發。
API 契約本質上是一成不變的，新增、更改或迭代它們通常既麻煩又困難。API 更改過程本身可能會令人沮喪和緩慢，並且錯誤可能會造成極高的代價。但隨著產品功能的增長，其 API 也應該增長——因此，擁有明確定義且執行良好的變更流程對企業至關重要。
 
我們著手實現兩個簡單的目標：
  1. 激勵更多 PagerDuty 工程和產品人員關心 API。
  2. 促進我們 API 的建立和維護。

 讓更多人做出貢獻不僅僅是宣傳 API Allies；這是透過簡化的工作流程賦予我們的開發人員、產品所有者和技術支援團隊權力的一種練習。首先，我們透過 GitHub Actions使用拉取請求模板和內聯 linting在我們的模式儲存庫中廣泛使用自動化 。我們還將我們的內部成功和支援團隊介紹給了 Stoplight Studio，它是 OpenAPI 模式的 GUI，因此他們甚至無需開啟文字編輯器就可以為我們的 API 文件做出貢獻。
在幾個月的更新過程中，我們聽到交付團隊的反饋說，釋出新的 API 端點令人生畏，因為在 PagerDuty，我們同意一旦釋出 API 端點，就不能對其進行重大更改。為了幫助團隊更輕鬆地構建新的 API 端點，我們開發了一個名為 Early Access Framework 的新工具。該工具使團隊可以輕鬆地將他們的 API 標記為早期訪問，這讓 API 的使用者知道合同可能會發生變化。它還為團隊提供有價值的使用資料，以便他們可以迭代他們的設計。
 
隨著 API Allies 的順利啟動和執行以及一些輕型工具的到位，我們決定需要專注於釋出更多 API。我們希望透過出色的文件和簡單的參與流程使團隊能夠做到這一點。我們著手建立一個輕量級框架，以獲取對新 API 新增和更改的評論。我們不希望 API Allies 成為我們 API 的看門人，因此我們設計了框架以推薦但不是必需的。該框架很簡單：
  1. 使用我們的API 變更提案模板建立提案。
  2. 透過 Slack 要求 API Allies 對提案進行審查，將分配兩名審查人員。
  3. 與指定的審閱者一起完善提案。
  4. 裝運它。

自從推出這個推薦的框架以來，我們已經有 10 多個交付團隊使用它，只有一個選擇不使用。我們相信高註冊率是信任交付團隊在佈局時遵循最佳實踐的結果。一個沒有使用該框架的團隊在設計他們的 API 模式時遇到了問題，從而推遲了他們的專案。
 
我們的架構是在 Swagger 2.0中 定義的，帶有用於打包和部署的自定義工具，並以非標準方式託管。對我們內部開發人員來說非常不友好：持續整合工具會不斷崩潰，因為它依賴於四個外部依賴項，並且有很多手動部署步驟。升級將透過減少與過時且記錄不完整的工具的接觸點來最大程度地減少摩擦；它還將使我們的工具與開源社群的其他成員保持一致，從而更容易獲得支援。
我們升級到 現代工具，依靠 Stoplight 為我們的文件提供服務，並轉向 開源社群。 為了與我們追求簡單性保持一致，我們透過將任何冗長的解釋移到我們的提案格式、為新開發人員維護常見問題解答文件以及引用外部文件以瞭解更復雜的概念（如 OpenAPI），從而減少了儲存庫中的文件數量。我們還使用我們的提案格式記錄了我們工具的升級，確保未來的開發人員能夠回過頭來看看我們做出特定決定的原因。
新工具使我們能夠透過三個步驟將更改部署到我們的 API 模式：
  1. 合併到內部儲存庫中。
  2. 合併到我們的公共架構 儲存庫中。
  3. 手動更新我們的 Postman 帳戶（遺憾的是，此步驟無法自動化）。





 

相關文章