1 使用描述性和有意義的資源名稱

選擇準(zhǔn)確表示所代表實體的資源名稱，不使用泛泛或模糊的名稱。

2 正確使用 HTTP 方法

針對不同的操作使用適當(dāng)?shù)?HTTP 方法（GET、POST、PUT、DELETE、PATCH 等）。

圖片

3 為 API 進(jìn)行版本控制

通過版本控制來確保向后兼容性，同時能夠在不破壞現(xiàn)有客戶端的情況下進(jìn)行未來的增強(qiáng)。

圖片

4 正確使用 HTTP 狀態(tài)碼

返回適當(dāng)?shù)?HTTP 狀態(tài)碼來指示 API 請求的成功或失敗。

圖片

5 選擇 JSON 字段命名約定（并堅持使用）

盡管 JSON 標(biāo)準(zhǔn)沒有強(qiáng)制規(guī)定字段命名約定，但根據(jù)最佳實踐，我們應(yīng)該選擇一種字段命名約定，并堅持使用。

圖片

6 使用一致的錯誤消息

在大多數(shù)情況下，僅僅依靠HTTP狀態(tài)碼無法很好地解釋錯誤的原因。為了幫助API使用者，應(yīng)該提供結(jié)構(gòu)化的JSON錯誤消息。這樣可以更清楚地說明錯誤的具體原因。

響應(yīng)應(yīng)包含以下信息：

• 錯誤代碼：一個機(jī)器可讀的錯誤代碼，用于標(biāo)識具體的錯誤情況。
• 錯誤消息：一個人類可讀的消息，提供詳細(xì)的錯誤說明。
• 錯誤上下文：與錯誤相關(guān)的附加信息，例如請求 ID、導(dǎo)致錯誤的請求參數(shù)或?qū)е洛e誤的請求中的字段。
• 錯誤鏈接：指向資源或文檔的 URL，提供關(guān)于錯誤以及如何解決錯誤的額外信息。
• 時間戳：錯誤發(fā)生的時間。

7 使用查詢參數(shù)進(jìn)行過濾、排序和搜索

查詢參數(shù)支持在HTTP請求的URL中提供附加信息，以便控制服務(wù)器返回的響應(yīng)。通過使用查詢參數(shù)，可以定制您所需的特定結(jié)果。

圖片

8 實現(xiàn)身份驗證和授權(quán)

通過實施適當(dāng)?shù)纳矸蒡炞C和授權(quán)機(jī)制來保護(hù) API。

• 對于身份驗證使用 API 密鑰、令牌或 OAuth 2.0。
• 對于授權(quán)應(yīng)用基于角色的訪問控制（RBAC）。

9 不要維護(hù)狀態(tài)

REST API 不應(yīng)該在服務(wù)器上維護(hù)狀態(tài)，這是客戶端的責(zé)任。

這一點非常重要，因為它使 API 可以進(jìn)行緩存、可擴(kuò)展，并且與客戶端解耦。

例如，電子商務(wù) API 可能使用 cookie 來維護(hù)購物車的狀態(tài)。然而，這種方法違反了 RESTful API 的關(guān)鍵原則——它們需要是無狀態(tài)的。

10 文檔化 API

為 API 提供全面的文檔，包括端點細(xì)節(jié)、請求/響應(yīng)示例和使用指南。

• 使用 Swagger/OpenAPI 文檔。
• 使用基于 Markdown 的文檔（例如使用 Swagger UI 或 ReDoc 等工具）。