如何快速實現(xiàn)REST API集成以優(yōu)化業(yè)務(wù)流程
你可能也喜歡這些API文章!
英文 | https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
翻譯 | 小愛你是否曾經(jīng)對可怕的API感到沮喪，而這一切都是猜謎游戲？好吧，我有。在這個微服務(wù)世界中，必須為后端API設(shè)計一致的接口。今天，我們將討論API的一些最佳實踐。
首先，需要了解一些術(shù)語
任何API設(shè)計都需要遵循一個稱為“Resource Oriented Design?”的概念，它包含三個關(guān)鍵概念
不好做法：
/systemOrders or /system_orders好的做法：
/ system-orders例如，如果你想從特定商店獲取產(chǎn)品。
不好做法：
/system-orders/{order_id} or /system-orders/{OrderId}好的做法：
/system-orders/{orderId}如果要獲取系統(tǒng)的所有用戶。
不好做法：
GET /user or GET /User好的做法：
GET /users如果要保持概念單一和一致。
不好做法：
GET /shops/:shopId/category/:categoryId/price好的做法：
GET /shops/:shopId/ or GET /category/:categoryId請勿使用動詞在URL中表達你的意圖。而是使用正確的HTTP方法來描述操作。
不好做法：
POST /updateuser/{userId} or GET /getusers好的做法：
PUT /user/{userId你有一個端點，該端點只返回一個操作。在這種情況下，你可以使用動態(tài)。例如，如果你想將警報重新發(fā)送給用戶。
不好做法：
POST /alerts/245743/resend請記住，這些不是我們的CRUD操作。相反，這些被認為是在我們的系統(tǒng)中起特定作用的功能。
如果要構(gòu)建請求主體或響應(yīng)為JSON的系統(tǒng)，則屬性名稱應(yīng)位于camelCase
不好做法：
{
user_name: "Mohammad Faisal"
user_id: "1"
}好的做法：
{
userName: "Mohammad Faisal"
userId: "1"
}RESTful HTTP服務(wù)必須實現(xiàn)/health和/version和/metrics API端點。他們將提供以下信息。
/health
/health用200 OK狀態(tài)碼響應(yīng)請求。
/version
/version用版本號響應(yīng)請求。
/metrics
該端點將提供各種指標，例如平均響應(yīng)時間。
/debug 并且 /status也強烈推薦端點。
不要只使用表名作為資源名。從長遠來看，這種懶惰可能是有害的。
不好做法：product_order
好的做法：product-orders
這是因為公開底層體系結(jié)構(gòu)不是你的目的。
有許多優(yōu)秀的API設(shè)計工具可用于提供良好的文檔，例如：
擁有良好而詳盡的文檔可以為n的API使用者帶來出色的用戶體驗。
始終對API使用版本控制，并一直將其向左移動，以使其具有最大的作用域。版本號應(yīng)為v1，v2等等。
好的：
http://api.domain.com/v1/shops/3/products始終在API中使用版本控制，因為如果外部實體正在使用該API，則更改端點可能會破壞其功能。
如果API返回了一個對象列表，則在響應(yīng)中始終包含資源總數(shù)。您可以total為此使用屬性。
不好做法：
{
users: [
...
]
}好的做法：
{
users: [
...
],
total: 34
}在操作中始終接受limit和offset參數(shù)GET。
好的：
GET /shops?offset=5&limit=5這是因為在前端進行分頁是必要的。
還應(yīng)考慮返回的數(shù)據(jù)量。添加fields參數(shù)以僅公開API中的必填字段。
例子：
只返回商店的名稱，地址和聯(lián)系方式。
GET /shops?fields=id,name,address,contact在某些情況下，它還有助于減小響應(yīng)大小。
這是非常不好的做法，因為通常會記錄URL，并且還會不必要地記錄身份驗證令牌。
不好做法：
GET / shops / 123？token = some_kind_of_authenticaiton_token好的：相反，將其傳遞給標頭：
Authorization: Bearer xxxxxx, Extra yyyyy另外，授權(quán)令牌應(yīng)該是短命的。
服務(wù)器不應(yīng)采用內(nèi)容類型。例如，如果您接受，application/x-www-form-urlencoded則攻擊者可以創(chuàng)建表單并觸發(fā)簡單的POST請求。
因此，請始終驗證content-type，如果您想使用默認的一種用法content-type: applicaiton/json
GET：檢索資源的表示形式。
POST：創(chuàng)建新的資源和子資源。
PUT：更新現(xiàn)有資源。
PATCH：更新現(xiàn)有資源。它僅更新所提供的字段，而其他字段不予處理
DELETE：刪除現(xiàn)有資源。
確實為所有面向公眾的API支持CORS（跨源資源共享）標頭。
考慮支持CORS允許的來源“ *”，并通過有效的OAuth令牌強制執(zhí)行授權(quán)。
避免將用戶憑據(jù)與原始驗證結(jié)合在一起。
跨所有端點，資源和服務(wù)強制實施HTTPS（TLS加密）。
對所有回調(diào)URL，推送通知終結(jié)點和webhooks強制實施并要求HTTPS。
當客戶端向服務(wù)提出無效或不正確的請求或向服務(wù)傳遞無效或不正確的數(shù)據(jù)時，就會發(fā)生錯誤，或更具體地說是服務(wù)錯誤。
示例包括無效的身份驗證憑據(jù)，不正確的參數(shù)，未知的版本ID等。
如果您對API格式的決定有疑問，這些黃金規(guī)則可以幫助指導(dǎo)我們做出正確的決定。
就是這樣-恭喜您已經(jīng)做到了！我希望你學(xué)到了一兩件事。
祝你編程愉快！
本文章轉(zhuǎn)載微信公眾號@web前端開發(fā)
鍵.png)
