設計出色API的最佳實踐與原則 - James

原則 1：永遠不應孤立地設計 API
從設計角度和編碼角度重新思考我們處理 API 的方式。放慢腳步，與那些有意見、主題專業知識的各方會面，讓他們與我們一起參與 API 設計，而不僅僅是推進程式碼。而是藉此機會將其轉變為以更多以產品為導向的體驗為中心的東西。
 

原則 2：基於結果的關注
誰將使用 API 以及他們正在嘗試做什麼
 

原則 3：與需求相匹配的設計元素
是否使用 Rest API 風格？我使用 GraphQL 嗎？gRPC 怎麼樣？當我們考慮 API 的設計元素時，我們需要考慮人們將如何使用 API。他們將在什麼環境下使用它？它主要來自網路瀏覽裝置、手機、平板電腦、膝上型電腦等嗎？是基於語音的嗎？是不是我們要與其他系統整合，所以我們需要一些事件？

• GraphQL：它非常適合它的響應深入塑造加工方面，可以製作一個看起來很像資料庫複雜的查詢，並且我可以非常具體地說明我想要的元素。
• 如果你有一個非常深的資源結構，你有很多巢狀的資源，你不想在查詢時進行查詢以越來越深入，團隊會選擇使用 REST 作為基礎，並輔以一些 GraphQL。
• 那麼也許如果他們需要一些高效能服務來服務通訊，他們會決定去 gRPC。透過內建的程式碼生成加快開發過程，並透過 gRPC 利用 HTTP/2 的一些效能改進來加速開發過程。一些標頭和其他內建內容的壓縮，以及雙向通訊。

原則 4：API 文件作為開發人員的 UI

• 作為正在尋找全新 API 的開發人員，參考文件非常重要。參考文件是我們花費大部分時間的地方。

原則 5：API 是永恆的

• 當我們考慮 Web API 時，我們不能只考慮可以重構和更改事物的程式碼庫。只要這一切都開始編譯並再次執行，我們就沒事了。我們談論的是分散式系統，其中的許多系統都不受使用它的其他人的控制。因此，那些使用您的 Web API 的人無法控制您作為提供者所做的事情，反之亦然。
• 我們必須制定有關如何管理版本控制（以及）如何處理它的策略，確保我們不會破壞人們，並確保我們不會每週或每個月都建立全新版本的 API。
• 透過不間斷更改、附加更改來增強 API 非常棒。那些型別的東西很棒。但是刪除東西，重新命名東西，那些會破壞使用該操作的人的東西，那些在響應中使用該特定欄位的人。
• 重構最終會改變你的 Web API，因為你沒有將 Web API 契約與你的實現細節分開，所以你無法讓它仍然按照設計的方式工作，即使你已經在內部改變了一些東西。如果您開始引入重大變化，那麼您將帶來客戶流失的機會。

API 設計優先方法

• 相對於程式碼優先的方法，想想我們如何做一個輕量級、快速的 API 設計優先方法，讓我們更接近正確的標記，防止我們編寫或設計一個不正確或與真正需要的不匹配的 API，並且仍然快速獲得反饋，以便我們並不是在自己的角落裡完全孤立地做這件事，而且做出這些改變太昂貴或太晚了。
• 對齊：我們如何確保我們設計的 API 與將要使用 API 的開發人員以及將間接使用該 API 的終端使用者對齊？首先要確保我們所有的假設都得到處理，我們不會編寫包含錯誤假設的程式碼。我們不會設計一個同樣具有錯誤假設的 API。我們瞭解需求是什麼，結果是什麼。我們將這些分解到下一個層次，並逐步瞭解我們需要做什麼。然後 API 設計將隨之發展。然後我們應用一種或多種 API 樣式來設計 API。因此，我們可能會對我們的大部分操作應用 REST 方法。也許提供一個 GraphQL。全部使用定義階段的輸出。一個 API 配置檔案，它定義了 API 應該在高層次上做什麼。

 
API 邊界和 DDD

• 引入邊界，我們可以在其中分割 API 的各個部分。這並不一定意味著您擁有多個 API 產品。這意味著您正在尋找具有凝聚力的不同 API 或不同操作。
• 花時間評估 API 的邊界位置將使您更高效，將範圍很大的產品或 API 操作的表面區域分解為更容易消化、更易於管理且更易於分解的更小的邊界區域由 API 提供商提供。
• 我們使用 EventStorming 作為發現我們可以佈置特定流程的好方法，從我們的事件開始，然後開始擴充套件並找到生成這些事件的命令，然後識別聚合，並詳細說明事件風暴過程。通常，這些聚合確實很好地暗示了 API 邊界在哪裡。
• 我們必須牢記許多 Web API，因為它們透過網路必須比我們的 DDD 程式碼庫更粗粒度，後者往往更細粒度並且可以在程式中執行。因此，當您使用具有 Web API 的分散式架構時，我們不希望有太多的網路流量。我們不想太健談。所以我們必須開始研究我們如何透過網路進行互動，這是一種不同於我們如何構建獨立程式碼庫和流程的架構風格。
• 看看 DDD，我們真的想首先關注聚合，然後讓聚合來幫助驅動 API 操作。