鍵.png)
使用這些基本 REST API 最佳實踐構(gòu)建出色的 API
在這次深入探討中，我們將深入了解API設(shè)計，從基礎(chǔ)知識開始，逐步進(jìn)階到定義出色API的最佳實踐。
作為開發(fā)者，你可能對許多這些概念很熟悉，但我將提供詳細(xì)的解釋，以加深你的理解。
讓我們考慮一個類似Shopify這樣的電子商務(wù)平臺的API。如果你不熟悉Shopify，它是一個著名的電子商務(wù)平臺，允許企業(yè)建立在線商店。
在API設(shè)計中，我們關(guān)注定義API的輸入（比如新產(chǎn)品的產(chǎn)品詳情）和輸出（比如當(dāng)某人查詢產(chǎn)品時返回的信息）。
這意味著我們關(guān)注的是接口而不是低級實現(xiàn)。
因此，焦點主要是定義CRUD操作如何向使用您的電子商務(wù)API的用戶或系統(tǒng)公開。
CRUD代表Create、Read、Update、Delete。這些是任何數(shù)據(jù)驅(qū)動應(yīng)用程序的基本操作。
例如，要添加新產(chǎn)品（創(chuàng)建），您將通過POST請求發(fā)送到/api/products，其中產(chǎn)品詳情包含在請求體中。
要檢索產(chǎn)品（讀取），您需要使用GET請求從/products獲取數(shù)據(jù)。
要更新產(chǎn)品信息（更新），我們使用PUT或PATCH請求到/products/:id，其中id是需要更新的產(chǎn)品的id。
刪除類似于更新；我們通過DELETE請求到/products/:id，其中id是需要移除的產(chǎn)品。
另一部分是決定要使用的通信協(xié)議，比如HTTP、WebSockets等，以及數(shù)據(jù)傳輸機(jī)制：JSON、XML或Protocol Buffers。
這適用于RESTful API，但我們還有GraphQL或gRPC范例。
API有不同的范例，每個范例都有其自己的一套協(xié)議和標(biāo)準(zhǔn)。
優(yōu)勢： 無狀態(tài)：客戶端到服務(wù)器的每個請求都必須包含理解和完成請求所需的所有信息。使用標(biāo)準(zhǔn)的HTTP方法（GET、POST、PUT、DELETE）。易于被不同客戶端（瀏覽器、移動應(yīng)用）消費。
缺點： 這可能導(dǎo)致數(shù)據(jù)的過多或過少獲取-因為可能需要更多的端點來訪問特定的數(shù)據(jù)。
特性： 支持分頁、過濾（**limit**、**offset**）和排序。使用JSON進(jìn)行數(shù)據(jù)交換。
優(yōu)勢： 允許客戶端請求確切需要的內(nèi)容，避免過多或過少獲取。基于強類型模式的查詢。
缺點： 復(fù)雜的查詢可能會影響服務(wù)器性能。所有請求都以POST請求發(fā)送。
特性： 通常以HTTP 200狀態(tài)碼回應(yīng)，即使在錯誤的情況下也是如此，并在響應(yīng)體中提供錯誤詳細(xì)信息。
優(yōu)勢： 構(gòu)建在HTTP/2之上，提供了高級功能，如多路復(fù)用和服務(wù)器推送。使用Protocol Buffers，一種語言中立、平臺中立、可擴(kuò)展的序列化結(jié)構(gòu)化數(shù)據(jù)的方式。在帶寬和資源方面效率高，特別適用于微服務(wù)。
缺點： 與JSON相比，可讀性較
差。需要支持HTTP/2。
特性： 支持?jǐn)?shù)據(jù)流和雙向通信。適用于服務(wù)器間通信。
在電子商務(wù)環(huán)境中，您可能會有諸如用戶到訂單、訂單到產(chǎn)品等的關(guān)系。
設(shè)計端點以反映這些關(guān)系是重要的。例如，在這種情況下，**GET /users/{userId}/orders**應(yīng)該為特定用戶獲取訂單。
常見的查詢還包括用于分頁的**limit**和**offset**，或者用于在某個日期范圍內(nèi)過濾產(chǎn)品的**startDate**和**endDate**。這允許用戶檢索特定集合的數(shù)據(jù)，而不會一次性向系統(tǒng)或用戶提供太多信息。
設(shè)計良好的GET請求是冪等的，這意味著多次調(diào)用它不會改變結(jié)果。
GET請求永遠(yuǎn)不應(yīng)該改變數(shù)據(jù)。它們只用于檢索。
在修改端點時，保持向后兼容性非常重要。這意味著確保更改不會破壞現(xiàn)有客戶端。
版本控制： 引入版本（比如**/v2/products**）是處理重大更改的常見做法。
在GraphQL的情況下，添加新字段（v2字段）而不刪除舊字段有助于在不破壞現(xiàn)有客戶端的情況下發(fā)展API。
另一個最佳實踐是設(shè)置速率限制。這用于控制用戶在一定時間內(nèi)可以發(fā)起的請求次數(shù)。這對于維護(hù)API的可靠性和可用性至關(guān)重要。它還防止API受到DDoS攻擊。
通常做法還包括設(shè)置CORS設(shè)置（跨域資源共享）。CORS設(shè)置對于Web安全至關(guān)重要。它們控制哪些域可以訪問您的API，防止不希望的跨站點交互。
本文章轉(zhuǎn)載微信公眾號@小技術(shù)君