22 條 API 設計的最佳實踐

譯者：劉志超，軟件工程師、DevOpsDays、HDZ 深圳核心組織者，目前供職於華爲，從事雲計算工作，專注於 K8s、微服務領域。

來源：dockone.io/article/2434604

原文：https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9

曾經因爲一個糟糕的 API 而感到沮喪嗎？

在這個微服務的世界裏，後端 API 的一致性設計是必不可少的。

今天，我們將討論一些可遵循的最佳實踐。我們將保持簡短和甜蜜——所以繫好安全帶，出發咯！

首先介紹一些術語

任何 API 設計都遵循一種叫做 “面向資源設計” 的原則：

• 資源：資源是數據的一部分，例如：用戶

• 集合：一組資源稱爲集合，例如：用戶列表

• URL：標識資源或集合的位置，例如：/user

1. 對 URL 使用 kebab-case（短橫線小寫隔開形式）

例如，如果你想要獲得訂單列表。

不應該：

/systemOrders或/system_orders

應該：

/system-orders

2. 參數使用 camelCase（駝峯形式）

例如，如果你想從一個特定的商店購買產品。

不應該：

/system-orders/{order_id}

或者：

/system-orders/{OrderId}

應該：

/system-orders/{orderId}

3. 指向集合的複數名稱

如果你想獲得系統的所有用戶。

不應該：

GET /user

或：

GET /User

應該：

GET /users

4. URL 以集合開始，以標識符結束

如果要保持概念的單一性和一致性。

不應該：

GET /shops/:shopId/category/:categoryId/price

這很糟糕，因爲它指向的是一個屬性而不是資源。

應該：

GET /shops/:shopId/或GET /category/:categoryId

5. 讓動詞遠離你的資源 URL

不要在 URL 中使用動詞來表達你的意圖。相反，使用適當的 HTTP 方法來描述操作。

不應該：

POST /updateuser/{userId}

或：

GET /getusers

應該：

PUT /user/{userId}

6. 對非資源 URL 使用動詞

如果你有一個端點，它只返回一個操作。在這種情況下，你可以使用動詞。例如，如果你想要向用戶重新發送警報。

應該：

POST /alarm/245743/resend

請記住，這些不是我們的 CRUD 操作。相反，它們被認爲是在我們的系統中執行特定工作的函數。

7. JSON 屬性使用 camelCase 駝峯形式

如果你正在構建一個請求體或響應體爲 JSON 的系統，那麼屬性名應該使用駝峯大小寫。

不應該：

{
   user_name: "Mohammad Faisal"
   user_id: "1"
}

應該：

{
   userName: "Mohammad Faisal"
   userId: "1"
}

8. 監控

RESTful HTTP 服務必須實現 / health 和 / version 和 / metricsAPI 端點。他們將提供以下信息。

/health

用 200 OK 狀態碼響應對 / health 的請求。

/version

用版本號響應對 / version 的請求。

/metrics

這個端點將提供各種指標，如平均響應時間。

也強烈推薦使用 / debug 和 / status 端點。

9. 不要使用 table_name 作爲資源名

不要只使用表名作爲資源名。從長遠來看，這種懶惰是有害的。

不應該：

product_order

應該：

product-orders

這是因爲公開底層體系結構不是你的目的。

10. 使用 API 設計工具

有許多好的 API 設計工具用於編寫好的文檔，例如：

• API 藍圖：https://apiblueprint.org/

• Swagger：https://swagger.io/

擁有良好而詳細的文檔可以爲 API 使用者帶來良好的用戶體驗。

11. 使用簡單序數作爲版本

始終對 API 使用版本控制，並將其向左移動，使其具有最大的作用域。版本號應該是 v1，v2 等等。

應該：http://api.domain.com/v1/shops/3/products

始終在 API 中使用版本控制，因爲如果 API 被外部實體使用，更改端點可能會破壞它們的功能。

12. 在你的響應體中包括總資源數

如果 API 返回一個對象列表，則響應中總是包含資源的總數。你可以爲此使用 total 屬性。

不應該：

{
  users: [ 
     ...
  ]
}

應該：

{
  users: [ 
     ...
  ],
  total: 34
}

13. 接受 limit 和 offset 參數

在 GET 操作中始終接受 limit 和 offset 參數。

應該：

GET /shops?offset=5&limit=5

這是因爲它對於前端的分頁是必要的。

14. 獲取字段查詢參數

返回的數據量也應該考慮在內。添加一個 fields 參數，只公開 API 中必需的字段。

例子：

只返回商店的名稱，地址和聯繫方式。

GET /shops?fields=id,name,address,contact

在某些情況下，它還有助於減少響應大小。

15. 不要在 URL 中通過認證令牌

這是一種非常糟糕的做法，因爲 url 經常被記錄，而身份驗證令牌也會被不必要地記錄。

不應該：

GET /shops/123?token=some_kind_of_authenticaiton_token

相反，通過頭部傳遞它們：

Authorization: Bearer xxxxxx, Extra yyyyy

此外，授權令牌應該是短暫有效期的。

16. 驗證內容類型

服務器不應該假定內容類型。例如，如果你接受 application/x-www-form-urlencoded，那麼攻擊者可以創建一個表單並觸發一個簡單的 POST 請求。

因此，始終驗證內容類型，如果你想使用默認的內容類型，請使用：

content-type: application/json

17. 對 CRUD 函數使用 HTTP 方法

HTTP 方法用於解釋 CRUD 功能。

GET：檢索資源的表示形式。

POST：創建新的資源和子資源。

PUT：更新現有資源。

PATCH：更新現有資源，它只更新提供的字段，而不更新其他字段。

DELETE：刪除已存在的資源。

18. 在嵌套資源的 URL 中使用關係

以下是一些實際例子：

• GET /shops/2/products：從 shop 2 獲取所有產品的列表。

• GET /shops/2/products/31：獲取產品 31 的詳細信息，產品 31 屬於 shop 2。

• DELETE /shops/2/products/31：應該刪除產品 31，它屬於商店 2。

• PUT /shops/2/products/31：應該更新產品 31 的信息，只在 resource-URL 上使用 PUT，而不是集合。

• POST /shops：應該創建一個新的商店，並返回創建的新商店的詳細信息。在集合 url 上使用 POST。

19. CORS（跨源資源共享）

一定要爲所有面向公共的 API 支持 CORS（跨源資源共享）頭部。

考慮支持 CORS 允許的 “*” 來源，並通過有效的 OAuth 令牌強制授權。

避免將用戶憑證與原始驗證相結合。

20. 安全

在所有端點、資源和服務上實施 HTTPS（tls 加密）。

強制並要求所有回調 url、推送通知端點和 webhooks 使用 HTTPS。

21. 錯誤

當客戶端向服務發出無效或不正確的請求，或向服務傳遞無效或不正確的數據，而服務拒絕該請求時，就會出現錯誤，或者更具體地說，出現服務錯誤。

例子包括無效的身份驗證憑證、不正確的參數、未知的版本 id 等。

• 當由於一個或多個服務錯誤而拒絕客戶端請求時，一定要返回 4xx HTTP 錯誤代碼。

• 考慮處理所有屬性，然後在單個響應中返回多個驗證問題。

22. 黃金法則

如果您對 API 格式的決定有疑問，這些黃金規則可以幫助我們做出正確的決定。

• 扁平比嵌套好。

• 簡單勝於複雜。

• 字符串比數字好。

• 一致性比定製更好。

就是這樣——如果你已經走到了這一步，恭喜你！希望你學到了一些東西。

希望你度過美好的一天！

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/WPJo3R8-s9YMow8a2_mENQ