了解 Rest API 開發(fā)中的 HTTP 方法
在設(shè)計和記錄 API 時，必須遵循 REST API 的基本原則。這包括識別資源并使用有意義的 URL 表示它們，適當(dāng)?shù)厥褂?HTTP 方法進行 CRUD（創(chuàng)建、讀取、更新、刪除）操作，以及以無狀態(tài)的方式管理資源狀態(tài)。通過采用面向資源的方法，開發(fā)團隊可以為客戶端開發(fā)人員設(shè)計直觀且易于使用的 REST API。REST API 文檔應(yīng)突出顯示可用的端點、支持的方法、接受和返回的數(shù)據(jù)格式，以及任何安全性或分頁約束。
API 風(fēng)格書籍在這一階段發(fā)揮著關(guān)鍵作用。它們提供了設(shè)計指南和標(biāo)準(zhǔn)，以確保開發(fā)的 API 一致性和質(zhì)量。這些樣式書定義了 URI 結(jié)構(gòu)、要使用的 HTTP 方法、數(shù)據(jù)格式、錯誤處理等規(guī)則，并可作為組織內(nèi) API 項目的通用參考。常用工具包括信號燈和 SwaggerHub，簡單的 Wiki 工具也足夠。
數(shù)據(jù)模型庫通過提供可重用的數(shù)據(jù)模型，定義 API 中使用的標(biāo)準(zhǔn)數(shù)據(jù)結(jié)構(gòu)，來完成這一階段。數(shù)據(jù)模型庫包括 JSON 模式、數(shù)據(jù)庫定義、對象模型等，提供現(xiàn)成的資產(chǎn)，減少錯誤，加速開發(fā)。常用工具有 Apicurio 和 Signal Lights。
API 門戶上的 API 經(jīng)常缺少工作流 API 的描述，這帶來了如下問題：
理解 API 調(diào)用的順序往往比較困難，但通常通過 API 門戶上的附加文檔進行補充。然而，這些文檔與開發(fā)人員提供的代碼分離。OpenAPI 規(guī)范允許定義鏈接和回調(diào)，但這在解釋過程中有限制。因此，最近出現(xiàn)了 OpenAPI 工作流規(guī)范，用于定義 API 工作流，這些步驟用 JSON 描述，允許生成模式來解釋調(diào)用順序。
如果希望從 OpenAPI 規(guī)范描述工作流，可以使用 Swagger Editor 或 SwaggerHub。也可以使用 Swagger to UML 或 OpenAPI to PlantUML。例如，可以使用 PlantUml 或 LucidChart 從設(shè)計序列圖開始。工具鏈的選擇取決于是否偏好自頂向下還是自底向上的方法。像 Stolight Studio 和 Redocly 這樣的工具，通常用于處理這些主題，Apicurio 也是如此。它們可以用于 API 設(shè)計，使團隊能夠使用用戶友好的界面輕松創(chuàng)建和可視化 OpenAPI 規(guī)范，并自動生成交互式文檔，確保文檔始終是最新的，并且與 API 規(guī)范保持一致。
一旦定義了 API 規(guī)范，下一步就是根據(jù)設(shè)計階段制定的指導(dǎo)方針和模型來開發(fā) API。敏捷軟件開發(fā)方法、有效的協(xié)作以及版本管理是確保高效開發(fā)的關(guān)鍵實踐。
對于版本控制，團隊使用 Git 或 GitHub 等版本控制系統(tǒng)來管理 API 源代碼。版本控制支持開發(fā)人員之間的無縫協(xié)作，并確保 API 隨時間變化的完全可跟蹤性。
在開發(fā)過程中，可以使用檢查工具來確保 API 規(guī)范的質(zhì)量。這些工具可以檢查以下內(nèi)容：
Swagger-Lint 和 Apicurio Studio 或 Stoltlight 可以用來執(zhí)行這些檢查，確保 API 規(guī)范的質(zhì)量。這些檢查也可以集成到 CI/CD 工具鏈中，以實現(xiàn)自動化和持續(xù)集成。
自動化在開發(fā)階段非常關(guān)鍵，可以通過工具如 Postman 和 Newman 進行單元、安全性和負載測試，以確保 API 的質(zhì)量和安全性。其他解決方案包括 REST Assured、Karate 和 K6。
支持 API REST 開發(fā)的框架非常常見，最流行的包括 Express.js（與 Node.js）、Spring Boot 和 Meteor。選擇合適的框架不僅要考慮其 API 能力，還需要符合開發(fā)團隊的需求和技術(shù)挑戰(zhàn)。
模擬原型也很重要，它可以減少開發(fā)人員之間的相互依賴。Mock API 通常基于 API 的 OpenAPI 描述進行創(chuàng)建，API 管理門戶通常會支持這一點。開源項目如 MockServer 和 WireMock 也是常用的模擬工具。
API安全性是開發(fā)和管理過程中的關(guān)鍵問題，涉及以下主要協(xié)議：
除了使用API密鑰、OAuth 2.0 和 OpenID Connect，您還可以部署集中管理工具如 Keycloak 來管理身份和API訪問。其替代品包括 OAuth2 Proxy、Gluu Server、WSO2 Identity Server 和 Apache Syncope。
不過，僅僅依賴這些工具和協(xié)議并不足以完全保障API安全。實現(xiàn) OWASP 規(guī)則的前端 Web 應(yīng)用程序防火墻 (WAF) 可以防止許多常見安全問題。為了更深入的安全管理，可以參考像 DZone Refcard 這樣的資源，或采用 DevSecOps 方法來降低風(fēng)險。
此外，自動化安全測試也是必不可少的，工具如 ZAP 可以進行自動化的安全測試，幫助識別和修復(fù)API中的潛在漏洞，確保API的穩(wěn)健性。
一旦開發(fā)了API，就需要在整個生命周期中有效地部署和管理它們。這包括版本管理、部署管理、性能監(jiān)控，以及確保API的可用性和可靠性。API管理平臺如Gravitee、Tyk、WSO2 API Manager、Google Cloud Apigee和Amazon API Gateway等，可以幫助進行API的部署、版本管理和監(jiān)控。這些平臺提供了一些高級特性，如緩存、速率限制、API安全性和配額管理。這些功能對于擴展規(guī)模非常重要。
為了確保符合設(shè)計階段建立的標(biāo)準(zhǔn)和指導(dǎo)方針，使用諸如stolight的spectrum之類的工具對OpenAPI規(guī)范進行檢查分析，識別潛在問題并確保API與設(shè)計標(biāo)準(zhǔn)的一致性。
當(dāng)然，在鏈的最后，你需要記錄你的API。現(xiàn)有的工具可以自動執(zhí)行許多任務(wù)，例如Redocly，它可以根據(jù)OpenAPI規(guī)范生成交互式文檔。額外的好處是，您可以確保您的文檔始終是最新的，并且對于每個人（開發(fā)人員和業(yè)務(wù)分析人員）都始終是簡單可讀的。
API管理還包括持續(xù)監(jiān)控API的性能、可用性和安全性，以及及時實施補丁和更新，以確保其順利運行。
API的分析和監(jiān)控對于確保其性能、可靠性和可用性至關(guān)重要。實時監(jiān)控API性能、收集使用數(shù)據(jù)并及早發(fā)現(xiàn)潛在問題是關(guān)鍵。ELK Stack（Elasticsearch、Logstash、Kibana）常用于收集、存儲和分析API訪問日志，以監(jiān)控性能和檢測錯誤。OpenTelemetry也是監(jiān)控端到端流程的好工具，特別是在包含API的復(fù)雜流程中。
在API性能指標(biāo)方面，Prometheus和Grafana是常用的實時監(jiān)控工具，能夠提供關(guān)于使用趨勢、瓶頸和性能問題的有價值信息。
顯然，您不需要一開始就準(zhǔn)備好所有這些工具和實踐來開始您的API開發(fā)之旅。您應(yīng)該首先考慮您希望如何開展工作以及您的優(yōu)先事項是什么。可能需要優(yōu)先考慮設(shè)計工具，如檢測工具，或定義您的API風(fēng)格書和API設(shè)計工具。優(yōu)先選擇常用的工具，避免重新發(fā)明輪子，是一個明智的策略。實際上，我建議您從建立工具鏈的基礎(chǔ)開始，因為這樣在后續(xù)階段的調(diào)整會更加容易。
希望這些要點能幫助您在確定API需求的優(yōu)先級時，能夠從容地開始您的工作。
原文鏈接：Get Some Rest! A Full API Stack
