如何使用 node.js 和 express 創建 rest api
你可能也喜歡這些API文章!
API建模是從多個角度定義API需要提供的功能的過程。它是一個迭代的過程，涉及到與API相關的人員，他們需要完成的任務，以及實現這些任務的步驟。通過API建模，我們可以更清晰地了解API的目標和用途。
API建模需要根據具體業務背景進行調整。例如，REST API的資源建模方式與GraphQL API的建模方式會有所不同。然而，無論使用何種風格，建模過程中遵循的基本步驟是一致的。
需要注意的是，這里討論的API建模是指定義API本身的過程，而不是利用API來輔助其他建模任務。例如，API財務建模是為財務建模提供支持的工具，而API主題建模則是為主題建模提供幫助的工具。
直接從數據庫開始設計API可能會導致API質量不佳，無法滿足所有用戶的需求。相反，我們需要從用戶的角度出發，考慮API需要支持的功能以及用戶的使用方式。
例如，在一個項目管理應用中，數據庫可能存儲了所有重要數據，但它并不能直接反映用戶的需求。如果僅僅從數據庫設計出發，我們可能會設計出一個CRUD風格的HTTP API，但這樣的API往往過于關注數據庫表，而忽略了用戶的實際需求。
API建?？梢詭椭覀冊谠O計API之前，建立更好的溝通實踐。通過建模，我們可以明確API存在的原因，以及它計劃解決的問題。
首先，需要明確誰會使用API。這些用戶可以是開發者、運營工程師、最終用戶，甚至是其他應用程序和設備。了解不同用戶的需求是建模的第一步。
例如，在一個項目管理應用中，我們可以將用戶分為以下幾類：
明確用戶角色不僅有助于API建模，還能為后續的文檔編寫提供支持。
用戶并不關心API的內部實現，他們關心的是API能實現哪些功能。例如，對于一個項目管理API，用戶可能希望能夠從頭到尾管理項目。
這些預期結果可能需要多個步驟來實現。在下一步中，我們將進一步分解這些步驟。
每個預期結果都由一系列步驟組成，每個步驟由API的一個或多個端點支持。通過分解步驟，我們可以更深入地了解API如何解決實際問題。
例如，在項目管理API中，管理項目的步驟可能包括：
在明確了所有步驟后，我們可以開始定義API模型。這包括確定API的資源和操作。此時，我們的目標是創建一個粗略的草圖，以驗證API需求。
例如，對于項目管理API，我們可能會定義以下資源和操作：
這些資源和操作為后續的API設計提供了基礎。
最后一步是驗證API模型是否滿足需求。通過線框圖、用戶故事和測試用例，我們可以確保API能夠滿足所有用戶的需求。
在驗證過程中，需要特別注意以下幾點：
以下是一些API建模的最佳實踐，幫助你更高效地完成建模工作：
花時間明確API的目標和用戶需求，這對成功的建模至關重要。
采用OpenAPI規范（OAS）或OpenTelemetry等標準，可以提高API的易用性和集成效率。
資源的命名應該清晰易懂，方便所有用戶理解。
在定義步驟和結果時，主題專家的參與可以提供寶貴的見解。
驗證階段是確保API模型符合需求的關鍵。不要急于跳過驗證，直接進入設計和開發。
通過API建模，我們可以更清晰地了解API需要支持的功能和實現這些功能的步驟。在此基礎上，我們可以選擇最適合的API設計風格。
例如，對于項目管理API，我們可能會選擇基于資源的方法，并應用REST約束。在這種情況下，可以將步驟映射到具體的API端點。
從建模到設計的過渡需要結合HTTP原則和API風格，最終形成完整的API設計。
原文鏈接: https://tyk.io/blog/before-you-design-your-api-model-your-api/
