API網(wǎng)關(guān)如何發(fā)展：更輕、更智能、云原生
你可能也喜歡這些API文章!
在 REST API 和 Web 服務(wù)領(lǐng)域，我們立即面臨著重要的安全任務(wù)。網(wǎng)絡(luò)威脅無處不在，因此 REST API 的安全至關(guān)重要。目標(biāo)是通過采用強(qiáng)大的身份驗(yàn)證和授權(quán)程序，僅授權(quán)用戶執(zhí)行操作。
SSL/TLS 協(xié)議的實(shí)施為我們的 (API) 通信提供了安全的通道。此外，監(jiān)控和記錄 API 活動(dòng)可充當(dāng)警衛(wèi)，識(shí)別和預(yù)防潛在威脅。
問題出現(xiàn)了——我們?nèi)绾尾拍苤幌蚝戏ㄓ脩羰谟璞驹L問權(quán)限？基于令牌的身份驗(yàn)證協(xié)議提供了解決方案。這些協(xié)議就像只有授權(quán)用戶才知道的秘密握手。其中，JSON Web 令牌 (JWT) 脫穎而出，成為一種流行的選擇，它充當(dāng)驗(yàn)證用戶身份和保護(hù)堡壘（API 端點(diǎn)）訪問的護(hù)照。
然而，這些護(hù)照的有效期很短，減少了未經(jīng)授權(quán)訪問的風(fēng)險(xiǎn)窗口。因此，JWT 和其短暫性相結(jié)合，形成了對(duì)入侵力量的強(qiáng)大防御。
然后，我們探討加密，這是我們安全工具包中的一個(gè)關(guān)鍵策略。傳輸層安全性 (TLS) 加密客戶端和服務(wù)器之間的數(shù)據(jù)傳輸，從而保護(hù) API 通信。
API 網(wǎng)關(guān)充當(dāng)保護(hù)盾，提供 TLS 或相互 TLS (mTLS) 等功能，這對(duì)于實(shí)現(xiàn)加密至關(guān)重要。這些加密標(biāo)準(zhǔn)類似于只有用戶才能理解的神秘語言，可確保信息的安全交換并阻止任何攔截其通信的企圖。
為保證敏感信息的安全傳輸，應(yīng)采取以下措施：
通過實(shí)施這些措施，您可以有效地保護(hù)敏感數(shù)據(jù)并確保 API 中的安全訪問數(shù)據(jù)。
堡壘的網(wǎng)關(guān)充當(dāng)著強(qiáng)大的保護(hù)層，在可疑請(qǐng)求到達(dá) API 之前將其過濾掉。同時(shí)，Web 應(yīng)用程序防火墻 (WAF) 可防范 DDoS 攻擊和其他惡意流量。通過實(shí)施這些措施，我們確保我們的珍寶——敏感數(shù)據(jù)——得到妥善保護(hù)。
結(jié)構(gòu)良好的 API 架構(gòu)注重設(shè)計(jì)的技術(shù)方面，從而打造高效、安全且用戶友好的環(huán)境。這包括清晰的標(biāo)識(shí)（資源命名）、簡單的路由（HTTP 方法）和結(jié)構(gòu)良好的層次結(jié)構(gòu)（嵌套資源）。
為了提供用戶友好的 API，請(qǐng)對(duì)資源集合使用復(fù)數(shù)形式（例如 /users），對(duì)單個(gè)資源使用單數(shù)名詞（例如 /users/123）。這可使 API 直觀且更易于理解。
這可確保您的 API 具有清晰的“標(biāo)志”，從而方便用戶使用。
標(biāo)準(zhǔn) HTTP 方法對(duì)于在 RESTful API 中執(zhí)行 CRUD 操作至關(guān)重要，類似于明確定義的程序指導(dǎo)操作的方式。這些方法是：
在設(shè)計(jì)端點(diǎn) URI 時(shí)，應(yīng)使用反映實(shí)體的清晰的名詞路徑，并且 HTTP 方法（而不是 URI）定義對(duì)資源的操作。將 HTTP 方法與其預(yù)期的 CRUD 操作對(duì)齊有助于為消費(fèi)者提供直觀且可預(yù)測(cè)的 API 交互。
在我們的應(yīng)用程序中，有許多部分，每個(gè)部分都有不同的角色。同樣，在 API 設(shè)計(jì)中，嵌套或相關(guān)資源必須具有結(jié)構(gòu)化的層次結(jié)構(gòu)，以促進(jìn)協(xié)作并最大限度地減少深度級(jí)別。嵌套資源應(yīng)使用分層 URI 來處理，以反映它們與單獨(dú)資源的關(guān)系，從而實(shí)現(xiàn)直觀的數(shù)據(jù)訪問和操作。
然而，在設(shè)計(jì)嵌套資源時(shí)，必須避免 URL 過長、冗余端點(diǎn)和不必要的數(shù)據(jù)庫查詢，因?yàn)檫@些會(huì)使 API 復(fù)雜化并降低效率。應(yīng)謹(jǐn)慎使用嵌套資源，以保持高效、可擴(kuò)展且易于使用的 API。因此，結(jié)構(gòu)良好的堡壘可讓用戶高效移動(dòng)和協(xié)作。
有效的響應(yīng)管理包括使用標(biāo)準(zhǔn) HTTP 狀態(tài)代碼、制作信息響應(yīng)主體以及實(shí)施速率限制以確保適當(dāng)?shù)?API 通信。
此請(qǐng)求的結(jié)果可以通過一個(gè)簡單的標(biāo)志系統(tǒng)來傳達(dá)。同樣，HTTP 狀態(tài)代碼充當(dāng)這些標(biāo)志，在服務(wù)器和客戶端之間傳達(dá) HTTP 請(qǐng)求（例如 API 請(qǐng)求）的結(jié)果。
不同的代碼表示不同的狀態(tài) – 操作成功、錯(cuò)誤或需要采取其他措施。遵守標(biāo)準(zhǔn) HTTP 狀態(tài)代碼并避免使用自定義代碼是一種最佳實(shí)踐，類似于遵循通用標(biāo)志代碼，可防止溝通錯(cuò)誤。
HTTP 狀態(tài)代碼使客戶端無需檢查響應(yīng)主體即可了解其請(qǐng)求的結(jié)果，從而立即清楚了解狀態(tài)代碼和請(qǐng)求的結(jié)果。
在 API 世界中，響應(yīng)主體就像是一份附有標(biāo)志的詳細(xì)報(bào)告。在 API 響應(yīng)的請(qǐng)求主體中同時(shí)包含請(qǐng)求的數(shù)據(jù)和相關(guān)元數(shù)據(jù)可以提高清晰度并提供關(guān)鍵上下文或附加信息。這就像用戶不僅知道他的請(qǐng)求被拒絕，還知道為什么被拒絕。
“X-Request-Id”響應(yīng)標(biāo)頭通過跟蹤服務(wù)器上的整個(gè)請(qǐng)求生命周期來幫助調(diào)試特定請(qǐng)求。用戶可以全面了解自己的請(qǐng)求，從發(fā)出請(qǐng)求到做出決定，這有助于理解和改進(jìn)未來的請(qǐng)求。
為了防止濫用和維持秩序，任何城堡都會(huì)限制請(qǐng)求或授予的觀眾數(shù)量。同樣，在 API 設(shè)計(jì)中，速率限制對(duì)于防止系統(tǒng)濫用和保持服務(wù)器性能至關(guān)重要。
實(shí)現(xiàn)速率限制的各種技術(shù)包括節(jié)流、請(qǐng)求隊(duì)列和基于算法的方法，如固定窗口、漏桶、滑動(dòng)日志和滑動(dòng)窗口。另一種策略是負(fù)載削減，即在系統(tǒng)接近過載時(shí)拒絕 API 請(qǐng)求以確保穩(wěn)定性。
API 通過響應(yīng)標(biāo)頭將速率限制和服務(wù)器狀態(tài)傳達(dá)給客戶端，指導(dǎo)用戶相應(yīng)地調(diào)整其請(qǐng)求模式。因此，速率限制就像守門人一樣，確保堡壘的平穩(wěn)運(yùn)行。
我們現(xiàn)在專注于應(yīng)用程序內(nèi)的信息交換。客戶端請(qǐng)求或用戶與服務(wù)器之間的高效數(shù)據(jù)交換對(duì)于優(yōu)化 REST API 中的客戶端-服務(wù)器數(shù)據(jù)交換至關(guān)重要。這涉及使用高效的數(shù)據(jù)序列化格式、內(nèi)容協(xié)商和壓縮技術(shù)。
在任何對(duì)話中，使用的語言都是至關(guān)重要的。在 API 設(shè)計(jì)中，選擇合適的數(shù)據(jù)格式（如 JSON）以實(shí)現(xiàn)兼容性和性能，就如同使用一種通用、高效的語言。JSON 數(shù)據(jù)采用鍵值對(duì)結(jié)構(gòu)，而 XML 數(shù)據(jù)采用分層樹模式表示，JSON 的簡單性使其更適合 API。了解 API 設(shè)計(jì)中使用的正確數(shù)據(jù)結(jié)構(gòu)對(duì)于有效溝通至關(guān)重要。
JSON 文件通常文件大小較小且更易于解析，從而加快數(shù)據(jù)傳輸速度并提高 API 性能。另一方面，XML 支持更多樣化的數(shù)據(jù)類型，在數(shù)據(jù)表示方面提供更大的靈活性。因此，選擇正確的數(shù)據(jù)格式就像選擇應(yīng)用程序內(nèi)最有效的通信語言一樣。
客戶端和服務(wù)器可能需要以各種格式交換數(shù)據(jù)。這時(shí)內(nèi)容協(xié)商就派上用場(chǎng)了，讓它們能夠就傳輸數(shù)據(jù)和要共享的文檔格式進(jìn)行溝通。
客戶端使用“Accept”標(biāo)頭來指定它們理解的媒體類型格式，而“Content-Type”標(biāo)頭則指示發(fā)送回客戶端的數(shù)據(jù)的媒體類型。在請(qǐng)求期間，客戶端可以向服務(wù)器端發(fā)送一個(gè)“Accept”標(biāo)頭，其中包含“application/json”或“application/xml”等值，以指示其偏好，而服務(wù)器則使用“Content-Type”標(biāo)頭進(jìn)行響應(yīng)，以指定發(fā)送的數(shù)據(jù)的格式。這類似于用戶和服務(wù)器就對(duì)話的通用語言達(dá)成一致。
gzip 和 brotli 等壓縮技術(shù)可以傳遞簡潔的信息，節(jié)省帶寬并提高網(wǎng)絡(luò)傳輸速度。
客戶端可以使用 HTTP 標(biāo)頭（例如“Accept-Encoding”）來指定它們支持的壓縮方法，服務(wù)器可以使用“Content-Encoding”來指示所提供內(nèi)容的壓縮方法。實(shí)施這些技術(shù)可以通過加速數(shù)據(jù)傳輸和減少延遲來顯著提高 API 性能。
配備高級(jí)功能的工具包始終具有優(yōu)勢(shì)。在 API 領(lǐng)域，高級(jí)查詢功能如下：
通過監(jiān)控和優(yōu)化 API 行為來增強(qiáng) API 功能。
假設(shè)一名抄寫員根據(jù)特定標(biāo)準(zhǔn)對(duì)卷軸進(jìn)行排序。API 世界中的過濾和排序工作方式類似。高效的做法會(huì)限制返回的無效數(shù)據(jù)量，從而優(yōu)化性能并節(jié)省服務(wù)器資源，尤其是在處理大型數(shù)據(jù)集時(shí)。
限制/偏移分頁使用“限制”參數(shù)來定義要返回的項(xiàng)目數(shù)，并使用“偏移”參數(shù)來指定起點(diǎn)，使其在 API 中易于實(shí)現(xiàn)。高級(jí)過濾機(jī)制利用帶有鍵值對(duì)的 URL 參數(shù)和運(yùn)算符（例如“gte”和“l(fā)te”）來表示范圍過濾器。
就像高級(jí)搜索選項(xiàng)可以簡化用戶查找所需信息的流程一樣，API 也受益于強(qiáng)大的搜索功能。這些功能允許過濾和選擇特定的數(shù)據(jù)字段，從而高效地檢索所需的內(nèi)容。API 可以通過支持復(fù)雜查詢來增強(qiáng)其搜索功能，從而啟用范圍搜索、術(shù)語匹配和模糊匹配等操作來優(yōu)化搜索結(jié)果。
為了擴(kuò)展搜索功能，API 可以利用 Lucene 或 ElasticSearch 等高級(jí)搜索技術(shù)啟發(fā)的語法，在搜索參數(shù)中實(shí)現(xiàn)過濾器和范圍。這就像騎士使用高級(jí)搜索技術(shù)來找到他需要的準(zhǔn)確卷軸一樣。
API 也會(huì)隨著時(shí)間的推移而發(fā)展。版本控制是 REST API 設(shè)計(jì)軟件開發(fā)不可或缺的一部分，可確保支持舊 API，同時(shí)系統(tǒng)地發(fā)布更新和新功能。它能夠以受控的方式引入新功能、糾正錯(cuò)誤并棄用過時(shí)的功能。
選擇合適的版本控制方法類似于規(guī)劃城堡的擴(kuò)建。URI 版本控制涉及將版本號(hào)直接包含在端點(diǎn) URL 中，這使得實(shí)現(xiàn)變得簡單，但會(huì)導(dǎo)致 URL 更長。查詢字符串參數(shù)版本控制將版本號(hào)放在 URL 的查詢參數(shù)中，從而產(chǎn)生更清晰的 URL。
標(biāo)頭版本控制將版本信息引入 HTTP 標(biāo)頭，從而保持干凈的 URL 并節(jié)省 URI 空間，但可能會(huì)增加客戶端請(qǐng)求的復(fù)雜性。媒體類型版本控制將版本數(shù)據(jù)嵌入 HTTP 標(biāo)頭中的媒體類型聲明中，從而實(shí)現(xiàn)對(duì)版本的精細(xì)控制。選擇正確的版本控制方法就像為應(yīng)用程序的擴(kuò)展選擇最有效的設(shè)計(jì)一樣。
在 API 設(shè)計(jì)中，棄用涉及逐步淘汰 API 功能，向 API 消費(fèi)者傳達(dá)這些即將發(fā)生的變化非常重要。
提前宣布變更并提供明確的時(shí)間表可確保用戶充分了解新功能和棄用的功能。將用戶過渡到新版本需要提供清晰的文檔和支持以促進(jìn)更新過程。因此，良好的溝通時(shí)間表可確保堡壘的居民能夠順利適應(yīng)變化。
全面的 API 設(shè)計(jì)文檔與產(chǎn)品構(gòu)建和維護(hù)藍(lán)圖一樣重要。文檔充當(dāng) API 的藍(lán)圖，為有效的 API 使用和采用提供基本信息。
API 契約類似于服務(wù)器和 API 之間的協(xié)議，明確雙方的期望。編寫良好的 API 契約的特點(diǎn)是簡單、一致，并且有詳盡的文檔，涵蓋輸入、輸出、錯(cuò)誤代碼和用例示例。
開放 API 規(guī)范等開發(fā)工具可以幫助確保傳入的數(shù)據(jù)符合預(yù)期的數(shù)據(jù)類型和屬性，在符合 API 契約的輸入驗(yàn)證中發(fā)揮關(guān)鍵作用。通過遵循 API 設(shè)計(jì)原則，將 API 契約測(cè)試自動(dòng)化作為持續(xù)集成過程的一部分，可以保持對(duì)定義的契約行為的遵守。
因此，清晰的 API 合同可確保每個(gè)人都知道自己的角色和職責(zé)。
繪制 API 藍(lán)圖需要一套適當(dāng)?shù)墓ぞ摺Ｔ?API 設(shè)計(jì)領(lǐng)域，Swagger 和 Postman 等工具對(duì)于編寫詳盡的文檔和測(cè)試 API 至關(guān)重要。
Swagger 和 Postman 直接連接到文檔，大大提高了 API 使用者的可發(fā)現(xiàn)性。這就像擁有不僅有助于繪制藍(lán)圖而且使堡壘所有居民都可以輕松訪問的工具。
API 的變更都有記錄，就像城堡翻新的更新一樣。使用發(fā)行說明和變更日志來傳達(dá) API 變更可確保用戶充分了解新功能和棄用的功能。
維護(hù)變更日志對(duì)于通知用戶更新（尤其是重大變更）以及確保其實(shí)現(xiàn)的持續(xù)功能至關(guān)重要。這就像在堡壘中記錄所有變更，幫助堡壘中的居民適應(yīng)這些變更。
文章來源：Mastering Good API Design Principles: The What, Why, and How
對(duì)比大模型API的內(nèi)容創(chuàng)意新穎性、情感共鳴力、商業(yè)轉(zhuǎn)化潛力
一鍵對(duì)比試用API 限時(shí)免費(fèi)
