在設計和記錄 API 時，必須遵循 REST API 的基本原則。這包括識別資源并使用有意義的 URL 表示它們，適當地使用 HTTP 方法進行 CRUD（創建、讀取、更新、刪除）操作，以及以無狀態的方式管理資源狀態。通過采用面向資源的方法，開發團隊可以為客戶端開發人員設計直觀且易于使用的 REST API。REST API 文檔應突出顯示可用的端點、支持的方法、接受和返回的數據格式，以及任何安全性或分頁約束。

API 風格書籍在這一階段發揮著關鍵作用。它們提供了設計指南和標準，以確保開發的 API 一致性和質量。這些樣式書定義了 URI 結構、要使用的 HTTP 方法、數據格式、錯誤處理等規則，并可作為組織內 API 項目的通用參考。常用工具包括信號燈和 SwaggerHub，簡單的 Wiki 工具也足夠。

數據模型庫通過提供可重用的數據模型，定義 API 中使用的標準數據結構，來完成這一階段。數據模型庫包括 JSON 模式、數據庫定義、對象模型等，提供現成的資產，減少錯誤，加速開發。常用工具有 Apicurio 和 Signal Lights。

API 門戶上的 API 經常缺少工作流 API 的描述，這帶來了如下問題：

• 如何鏈接 API 調用？
• 如何描述這些調用的順序？用圖示還是文本？
• 如何確保最了解 API 的人能夠讀懂并定期更新？

理解 API 調用的順序往往比較困難，但通常通過 API 門戶上的附加文檔進行補充。然而，這些文檔與開發人員提供的代碼分離。OpenAPI 規范允許定義鏈接和回調，但這在解釋過程中有限制。因此，最近出現了 OpenAPI 工作流規范，用于定義 API 工作流，這些步驟用 JSON 描述，允許生成模式來解釋調用順序。

如果希望從 OpenAPI 規范描述工作流，可以使用 Swagger Editor 或 SwaggerHub。也可以使用 Swagger to UML 或 OpenAPI to PlantUML。例如，可以使用 PlantUml 或 LucidChart 從設計序列圖開始。工具鏈的選擇取決于是否偏好自頂向下還是自底向上的方法。像 Stolight Studio 和 Redocly 這樣的工具，通常用于處理這些主題，Apicurio 也是如此。它們可以用于 API 設計，使團隊能夠使用用戶友好的界面輕松創建和可視化 OpenAPI 規范，并自動生成交互式文檔，確保文檔始終是最新的，并且與 API 規范保持一致。

API 開發

一旦定義了 API 規范，下一步就是根據設計階段制定的指導方針和模型來開發 API。敏捷軟件開發方法、有效的協作以及版本管理是確保高效開發的關鍵實踐。

對于版本控制，團隊使用 Git 或 GitHub 等版本控制系統來管理 API 源代碼。版本控制支持開發人員之間的無縫協作，并確保 API 隨時間變化的完全可跟蹤性。

在開發過程中，可以使用檢查工具來確保 API 規范的質量。這些工具可以檢查以下內容：

• 代碼的語法和結構
• 遵守編碼標準和命名約定
• 正確使用庫和框架
• 是否存在死代碼或冗余代碼
• 潛在的安全問題

Swagger-Lint 和 Apicurio Studio 或 Stoltlight 可以用來執行這些檢查，確保 API 規范的質量。這些檢查也可以集成到 CI/CD 工具鏈中，以實現自動化和持續集成。

自動化在開發階段非常關鍵，可以通過工具如 Postman 和 Newman 進行單元、安全性和負載測試，以確保 API 的質量和安全性。其他解決方案包括 REST Assured、Karate 和 K6。

支持 API REST 開發的框架非常常見，最流行的包括 Express.js（與 Node.js）、Spring Boot 和 Meteor。選擇合適的框架不僅要考慮其 API 能力，還需要符合開發團隊的需求和技術挑戰。

模擬原型也很重要，它可以減少開發人員之間的相互依賴。Mock API 通常基于 API 的 OpenAPI 描述進行創建，API 管理門戶通常會支持這一點。開源項目如 MockServer 和 WireMock 也是常用的模擬工具。

API 的安全

API安全性是開發和管理過程中的關鍵問題，涉及以下主要協議：

1. API密鑰：由于其易用性和低開銷，API密鑰仍廣泛用于API訪問。它們以一對唯一字符的形式存在，應像密碼一樣安全地存儲。
2. OAuth 2.0：一種基于令牌的身份驗證方法，涉及三個參與者：用戶、集成應用程序（通常是API網關）和目標應用程序。用戶通過OAuth端點交換令牌，授予應用程序對服務提供者的訪問權限。OAuth 2.0因其粒度訪問控制和基于時間的限制而受到青睞。
3. OpenID Connect：這是OAuth 2.0的擴展，增加了標準化的第三方標識和用戶身份，適用于細粒度授權控制和管理多個身份提供者，盡管并非所有API提供者都需要它。

除了使用API密鑰、OAuth 2.0 和 OpenID Connect，您還可以部署集中管理工具如 Keycloak 來管理身份和API訪問。其替代品包括 OAuth2 Proxy、Gluu Server、WSO2 Identity Server 和 Apache Syncope。

不過，僅僅依賴這些工具和協議并不足以完全保障API安全。實現 OWASP 規則的前端 Web 應用程序防火墻 (WAF) 可以防止許多常見安全問題。為了更深入的安全管理，可以參考像 DZone Refcard 這樣的資源，或采用 DevSecOps 方法來降低風險。

此外，自動化安全測試也是必不可少的，工具如 ZAP 可以進行自動化的安全測試，幫助識別和修復API中的潛在漏洞，確保API的穩健性。

API 生命周期管理

一旦開發了API，就需要在整個生命周期中有效地部署和管理它們。這包括版本管理、部署管理、性能監控，以及確保API的可用性和可靠性。API管理平臺如Gravitee、Tyk、WSO2 API Manager、Google Cloud Apigee和Amazon API Gateway等，可以幫助進行API的部署、版本管理和監控。這些平臺提供了一些高級特性，如緩存、速率限制、API安全性和配額管理。這些功能對于擴展規模非常重要。

為了確保符合設計階段建立的標準和指導方針，使用諸如stolight的spectrum之類的工具對OpenAPI規范進行檢查分析，識別潛在問題并確保API與設計標準的一致性。

當然，在鏈的最后，你需要記錄你的API。現有的工具可以自動執行許多任務，例如Redocly，它可以根據OpenAPI規范生成交互式文檔。額外的好處是，您可以確保您的文檔始終是最新的，并且對于每個人（開發人員和業務分析人員）都始終是簡單可讀的。

API管理還包括持續監控API的性能、可用性和安全性，以及及時實施補丁和更新，以確保其順利運行。

API 性能監控與優化

API的分析和監控對于確保其性能、可靠性和可用性至關重要。實時監控API性能、收集使用數據并及早發現潛在問題是關鍵。ELK Stack（Elasticsearch、Logstash、Kibana）常用于收集、存儲和分析API訪問日志，以監控性能和檢測錯誤。OpenTelemetry也是監控端到端流程的好工具，特別是在包含API的復雜流程中。

在API性能指標方面，Prometheus和Grafana是常用的實時監控工具，能夠提供關于使用趨勢、瓶頸和性能問題的有價值信息。

總結

顯然，您不需要一開始就準備好所有這些工具和實踐來開始您的API開發之旅。您應該首先考慮您希望如何開展工作以及您的優先事項是什么。可能需要優先考慮設計工具，如檢測工具，或定義您的API風格書和API設計工具。優先選擇常用的工具，避免重新發明輪子，是一個明智的策略。實際上，我建議您從建立工具鏈的基礎開始，因為這樣在后續階段的調整會更加容易。

希望這些要點能幫助您在確定API需求的優先級時，能夠從容地開始您的工作。

原文鏈接：Get Some Rest! A Full API Stack