22種使你的API設計技能更上一層樓的最佳實踐方案

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

翻譯 | 小愛

你是否曾經對可怕的API感到沮喪，而這一切都是猜謎遊戲？好吧，我有。

在這個微服務世界中，必須為後端API設計一緻的接口。今天，我們将讨論API的一些最佳實踐。

首先，需要了解一些術語

任何API設計都需要遵循一個稱為“Resource Oriented Design ”的概念，它包含三個關鍵概念

• 資源：資源是一條資料，例如User。
• 集合：一組資源稱為集合，示例：使用者清單
• URL：辨別資源或集合的位置。例子：/user

1、使用kebab-case作為URL

例如，如果要擷取訂單清單。

不好做法：

/systemOrders or /system_orders      

好的做法：

/ system-orders      

2、使用camelCase作為參數

例如，如果你想從特定商店擷取産品。

不好做法：

/system-orders/{order_id} or /system-orders/{OrderId}      

好的做法：

/system-orders/{orderId}      

3、指向集合的複數名稱

如果要擷取系統的所有使用者。

不好做法：

GET /user or GET /User      

好的做法：

GET /users      

4、 URL以集合開頭，以辨別符結尾

如果要保持概念單一和一緻。

不好做法：

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

好的做法：

GET /shops/:shopId/ or GET /category/:categoryId      

5、避免動詞進入你的資源URL

請勿使用動詞在URL中表達你的意圖。而是使用正确的HTTP方法來描述操作。

不好做法：

POST /updateuser/{userId} or GET /getusers      

好的做法：

PUT /user/{userId      

6、對非資源URL使用動态

你有一個端點，該端點隻傳回一個操作。在這種情況下，你可以使用動态。例如，如果你想将警報重新發送給使用者。

不好做法：

POST /alerts/245743/resend      

請記住，這些不是我們的CRUD操作。相反，這些被認為是在我們的系統中起特定作用的功能。

7、使用camelCase作為JSON屬性

如果要建構請求主體或響應為JSON的系統，則屬性名稱應位于camelCase

不好做法：

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

好的做法：

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

8、監控

RESTful HTTP服務必須實作/health和/version和/metrics API端點。他們将提供以下資訊。

/health

/health用200 OK狀态碼響應請求。

/version

/version用版本号響應請求。

/metrics

該端點将提供各種名額，例如平均響應時間。

/debug 并且 /status也強烈推薦端點。

9、不要使用table_name作為資源名稱

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

不好做法：product_order

好的做法：product-orders

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

10、使用API設計工具

有許多優秀的API設計工具可用于提供良好的文檔，例如：

• API藍圖：https://apiblueprint.org/
• 昂首闊步：https://swagger.io/

擁有良好而詳盡的文檔可以為n的API使用者帶來出色的使用者體驗。

11、使用簡單序号作為版本ni

始終對API使用版本控制，并一直将其向左移動，以使其具有最大的作用域。版本号應為v1，v2等等。

好的：

http://api.domain.com/v1/shops/3/products      

始終在API中使用版本控制，因為如果外部實體正在使用該API，則更改端點可能會破壞其功能。

12、在響應中包括資源總數

如果API傳回了一個對象清單，則在響應中始終包含資源總數。您可以total為此使用屬性。

不好做法：

{
  users: [ 
     ...
  ]
}      

好的做法：

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

13、接受極限和偏移參數

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

好的：

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，如果您想使用預設的一種用法content-type: applicaiton/json

17、對CRUD功能使用HTTP方法

HTTP方法用于解釋CRUD功能。

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

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

PUT：更新現有資源。

PATCH：更新現有資源。它僅更新所提供的字段，而其他字段不予處理

DELETE：删除現有資源。

18、在URL中将關系用于嵌套資源

一些實際的例子是：

• GET /shops/2/products ：從商店2擷取所有産品的清單。
• GET /shops/2/products/31：擷取屬于商店2的産品31的詳細資訊。
• DELETE /shops/2/products/31 ，應删除屬于商店2的産品31。
• PUT /shops/2/products/31 ，應更新産品31（僅在資源URL上使用PUT，而不是集合）上的資訊。
• POST /shops，應建立一個新商店并傳回建立的新商店的詳細資訊。在collection-URL上使用POST。

19、 CORS

确實為所有面向公衆的API支援CORS（跨源資源共享）标頭。

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

避免将使用者憑據與原始驗證結合在一起。

20、安全性

跨所有端點，資源和服務強制實施HTTPS（TLS加密）。

對所有回調URL，推送通知終結點和webhooks強制實施并要求HTTPS。

21、錯誤

當用戶端向服務提出無效或不正确的請求或向服務傳遞無效或不正确的資料時，就會發生錯誤，或更具體地說是服務錯誤。

示例包括無效的身份驗證憑據，不正确的參數，未知的版本ID等。

• 4xx當由于一個或多個服務錯誤而拒絕用戶端請求時，請傳回HTTP錯誤代碼。
• 考慮處理所有屬性，然後在單個響應中傳回多個驗證問題。

22、黃金法則

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

• 扁平比嵌套更好。
• 簡單勝于複雜。
• 字元串勝于數字。
• 一緻性比自定義更好。

就是這樣-恭喜您已經做到了！我希望你學到了一兩件事。

祝你程式設計愉快！