13 個設計 REST API 的最佳實踐

HaoliangWu發表於2018-12-20

原文 RESTful API Design: 13 Best Practices to Make Your Users Happy

寫在前面

之所以翻譯這篇文章,是因為自從成為一名前端碼農之後,調介面這件事情就成為了家常便飯,並且,還伴隨著無數的爭論與無奈。編寫友好的 restful api 不論對於你的同事,還是將來作為第三方服務呼叫介面的使用者來說,都顯得至關重要。關於 restful api 本身以及設計原則,我陸陸續續也看過很多的文章和書籍,在讀過原文後,感覺文中指出的 13 點最佳實踐還是比較全面的且具有參考意義的,因此翻譯出來分享給大家。如有錯誤,還望指正。

由於我一般傾向於意譯,關於原文中的開頭語或者一些與之無關的內容,我就省略掉了,畢竟時間是金錢,英語好並且能科學上網的朋友我建議還是看原文,以免造成理解上的誤差。

1. 瞭解應用於 REST 之上的 HTTP 知識

如果你想要構建設計優良的 REST API,瞭解一些關於 HTTP 協議的基礎知識是很有幫助的,畢竟磨刀不誤砍材工。

在 MDN 上有很多質量不錯的文件介紹 HTTP。但是,就 REST API 設計本身而言,所涉及到的 HTTP 知識要點大概包含以下幾條:

  • HTTP 中包含動詞(或方法): GETPOSTPUTPATCH 還有 DELETE 是最常用的。
  • REST 是面向資源的,一個資源被一個 URI 所標識,比如 /articles/
  • 端點(endpoint),一般指動詞與 URI 的組合,比如 GET: /articles/
  • 一個端點可以被解釋為對某種資源進行的某個動作。比如, POST: /articles 可能代表“建立一個新的 article”。
  • 在業務領域,我們常常可以將動詞CRUD(增刪查改)關聯起來:GET 代表查,POST代表增,PUTPATCH 代表改(注: PUT 通常代表整體更新,而 PATCH 代表區域性更新),而 DELETE 代表刪。

當然了,你可以將 HTTP 協議中所提供的任何東西應用於 REST API 的設計之中,但以上這些是比較基礎的,因此時刻將它們記在腦海中是很有必要的。

2. 不要返回純文字

雖然返回 JSON 資料格式的資料不是 REST 架構規範強制限定的,但大多 REST API 都遵循這條準則。

但是,僅僅返回 JSON 資料格式的資料還是不夠的,你還需要指定返回 body 的頭部,比如 Content-Type,它的值必須指定為 application/json。這一點對於程式化客戶端尤為重要(比如通過 python 的 requests 模組來與 api 進行互動)—— 這些程式是否對返回資料進行正確解碼取決於這個頭部。

注:通常而言,對於瀏覽器來說,這似乎不是問題,因為瀏覽器一般都自帶內容嗅探機制,但為了保持一致性,還是在響應中設定這個頭部比較妥當。

3. 避免在 URI 中使用動詞

如果你理解了第 1 條最佳實踐所傳達的意思,那麼你現在就會明白不要將動詞放入 REST API 的 URI 中。這是因為 HTTP 的動詞已經足以描述執行於資源的業務邏輯操作了。

舉個例子,當你想要提供一個針對某個 article 提供 banner 圖片並返回的介面時,可能會實現如下格式的介面:

GET: /articles/:slug/generateBanner/複製程式碼

這裡 GET 已經說明了這個介面是在做的操作,因此,可以簡化為:

GET: /articles/:slug/banner/複製程式碼

類似的,如果這個埠是要建立一個 article:

// 不要這麼做POST: /articles/createNewArticle/// 這才是最佳實踐POST: /articles/複製程式碼

嘗試用 HTTP 的動詞來描述所涉及的業務邏輯操作。

4. 使用複數的名詞來描述資源

一些時候,使用資源的複數形式還是單數形式確實存在一定的困擾,比如使用 /article/:id/ 更好還是使用 /articles/:id/ 更好呢?

這裡我推薦使用後者。為什麼呢?因為複數形式可以滿足所有型別端點的需求。

單數形式的 GET /article/2/ 看起來還是不錯的,但是如果是 GET /article/ 呢?你能夠僅通過字面資訊來區分這個介面是返回某個 article 還是多個呢?

因此,為了避免有單數命名造成的歧義性,並儘可能的保持一致性,使用複數形式,比如:

GET: /articles/2/POST: /articles/...複製程式碼

5. 在響應中返回錯誤詳情

當 API 伺服器處理錯誤時,如果能夠在返回的 JSON body 中包含錯誤資訊,對於介面呼叫者來說,會一定程度上幫助他們完成除錯。比如對於常見的提交表單,當遇到如下錯誤資訊時:

{ 
"error": "Invalid payoad.", "detail": {
"surname": "This field is required."
}
}複製程式碼

介面呼叫者很快就是明白髮生錯誤的原因。

6. 小心 status code

這一點可能是最重要、最重要、最重要的一點,可能也是這篇文章中,唯一你需要記住的那一點。

你可能知道,HTTP 中你可以返回帶有 200 狀態碼的錯誤響應,但這是十分糟糕的。不要這麼做,你應當返回與返回錯誤型別相一致的具有一定含義的狀態碼

聰明的讀者可能會說,我按照第 5 點最佳實踐來提供足夠詳細的資訊,難道不行嗎?當然可以,不過讓我講一個故事:

我曾經使用過一個 API,對於它返回的所有響應的狀態碼均是 200 OK,同時通過響應資料中的 status 欄位來表示當前的請求是否成功,比如:

{ 
"status": "success", "data": {
}
}複製程式碼

所以,雖然狀態碼是 200 OK,但我卻不能絕對確定請求是否成功,事實上,當錯誤發生時,這個 API 會按如下程式碼片段返回響應:

HTTP/1.1 200 OKContent-Type: text/html{ 
"status": "failure", "data": {
"error": "Expected at least two items in list."
}
}複製程式碼

頭部還是 text/html,因為它同時返回了一些 HTML 片段。

正因為這樣,我不得不在檢查響應狀態碼正確的同時,還需校驗這個具有特殊含義的 status 欄位的值,才可以放心的處理響應返回的 data

這種設計的一個真正壞處在於,它打破了介面與呼叫者之間的“信任”,因為你可能會擔心這個介面對你撒謊(注:言外之意就是,由於特設的欄位可能會改變,因此增加了不可靠性)。

所以,使用正確的狀態碼,同時僅在響應的 body 中返回錯誤資訊,並設定正確的頭部,比如:

HTTP/1.1 400 Bad RequestContent-Type: application/json{ 
"error": "Expected at least two items in list."
}複製程式碼

7. 保持 status code 的一致性

當你掌握了正確使用狀態碼之後,就應該努力使它們具有一致性。

比如,如果一個 POST 型別的端點返回 201 Created,那麼所有的 POST 端點都應返回同樣的狀態碼。這樣做的好處在於,呼叫者無需在意端點返回的狀態碼取決於某種特殊條件,也就形成了一致性。如果有特殊情況,請在文件中顯著地說明它們。

下面是我推薦的與動詞相對應的狀態碼:

GET: 200 OKPOST: 201 CreatedPUT: 200 OKPATCH: 200 OKDELETE: 204 No Content複製程式碼

8. 不要巢狀資源

使用 REST API 獲取資源資料,通常情況下會直接獲取多個或者單個,但當我們需要獲取相關聯的資源時,該怎麼做呢?

比如說,我們期望獲取作者為某個 author 的 article 列表 —— 假設 authro 的 id=12。這裡提供兩種方案:

第一種方案通過在 URI 中,將巢狀的資源放在所關聯的資源後邊來進行描述,比如:

GET: /authors/12/articles/複製程式碼

一些人推薦這種方案的理由是,這種形式的 URI 一定程度上描述了 author 與 article 之間的一對多關係。但與此同時,結合第 4 點最佳實踐,我們就不太能夠分清當前端點返回的資料到底是 author 型別還是 article 型別。

這裡有一篇文章,詳細闡述了扁平化形式優於巢狀形式,因此一定有更好的方法,這就是下面的第二種方案:

GET: /articles/?author_id=12複製程式碼

直接將篩選 article 的邏輯抽離為 querystring 即可,這樣的 URI 相比之前,更加清晰地描述了“獲取所有 author(id=12) 的 article”的意思。

9. 優雅地處理尾部斜槓

一個好的 URI 中是否應當包含尾部斜槓,並不具有探討價值,選擇一種更傾向的風格並保持一致性即可,同時當客戶端誤用尾部斜槓時,提供重定向響應。

我再來講我自己的一個故事。某天,我在將某個 API 端點整合到專案中,但是我總是收到 500 Internal Error 的錯誤,我呼叫的端點差不多看起來這樣:

POST: /entities複製程式碼

除錯一段時間之後,我幾乎崩潰了,因為我根本不知道我哪裡做錯了,直到我發現伺服器之所以報 500 的錯誤,是因為我粗心丟掉了尾部斜槓(注:這種經歷人人都會遇到,我在 SF 上遇過無數次類似的問題),當我把 URI 改成:

POST: /entities/複製程式碼

之後,一切正常運轉。

當然,大多數的 web 框架都針對 URL 是否包含尾部斜槓,進行了優雅地處理並提供定製選項,如果可以的話,找到它並開啟這項功能。

10. 使用 querystring 來完成篩選和分頁功能

大部分情況下,一個簡單的端點沒有辦法滿足負責業務場景。

你的使用者可能想要獲取滿足一定條件下的某些資料集合 ,同時為了保證效能,僅僅獲取這個集合下的一個子集。換言之,這通常叫作篩選功能和分頁功能:

  • 篩選:使用者可以提供額外的屬性來控制返回的資料集合
  • 分頁:獲取資料集合的子集,最簡單的分頁是基於分頁個數的分頁,它由 pagepage_size 來決定

那麼問題來了,我們如何將這兩項功能與 RESTful API 結合在一起呢?

答案當然是通過 querystring。對於分頁,很顯然使用這種方式再合適不過了,比如:

GET: /articles/?page=1&
page_size=10複製程式碼

但對於篩選,你可能會犯第 8 點最佳實踐中所指出的問題,比如獲取處於 published 狀態的 article 列表:

GET: /articles/published/複製程式碼

除了之前提出的問題外,這裡還涉及一個設計上的問題,就是 published 本身不是資源,它僅僅是資源的特徵,類似這種特徵欄位,應該將它們放到 querystring 中:

GET: /articles/?published=true&
page=2&
page_size=20複製程式碼

更加優雅、清晰,不是嗎?

11. 分清 401 和 403

當我們遇到 API 中關於安全的錯誤提示時,很容易混淆這兩個不同型別的錯誤,認證授權(比如許可權相關)—— 老實講,我自己也經常搞混。

這裡是我自己總結的備忘錄,它闡述了我如何在實際情況下,區分它們:

  • 使用者是否未提供身份驗證憑據?認證是否還有效?這種型別的錯誤一般是未認證(401 Unauthorized)。
  • 使用者經過了正常的身份驗證,但沒有訪問資源所需的許可權?這種一般是未授權(403 Forbidden

12. 巧用 202 Accepted

我發現 202 Accepted 在某些場合是 201 Created 的一個非常便捷的替代方案,這個狀態碼的含義是:

伺服器已經接受了你的請求,但是到目前為止還未建立新的資源,但一切仍處於正常狀態。

我分享兩種特別適合使用 202 Accepted 狀態碼的業務場景:

  • 如果資源是經過位於將來一系列處理流程之後才建立的,比如當某項作業完成時
  • 如果資源已經存在,但這是理想狀態,因此不應該被識別為一個錯誤時

13. 採用 REST API 定製化的框架

作為最後一個最佳實踐,讓我們來探討這樣一個問題:你如何在 API 的實施中,實踐最佳實踐呢?

通常的情況是這樣的,你想要快速建立一個 API 以便一些服務可以互相訪問彼此。Python 開發者可能馬上掏出了 Flask,而 JS 開發者也不甘示弱,祭出了 Express,他們會使用實現一些簡單的 routes 來處理 HTTP 請求。

但這樣做的問題是,通常,web 框架並不是針對構建 REST API 服務而專門存在的,換言之,Flask 和 Express 是兩個十分通用的框架,但它們並非特別適合用於構建 REST API 服務。因此,你必須採取額外的步驟來實施 API 中的最佳實踐,但大多數情況下,由於懶惰或者時間緊張等因素,意味著你不會投入過多精力在這些方面 —— 然後給你的使用者提供了一個古怪的 API 端點。

解決方案十分簡單:工欲善其事,必先利其器,掌握並使用正確的工作才是最好的方案。在各種語言中,許多專門用於構建 REST API 服務的新框架已經出現了,它們可以幫助你在不犧牲生產力的情況下,輕鬆地完成工作,同時遵循最佳實踐。在 Python 中,我發現的最好的 API 框架之一是 Falcon。它與 Flask 一樣簡單,非常高效,十分適合構建 REST API 服務。如果你更喜歡 Django 的話,使用 Django REST Framework就足夠了,雖然框架不是那麼直觀(注:按我的理解應該是說不太容易上手,但是我不這麼認為),但功能非常強大。在 NodeJS 中,Restify 似乎也是一個不錯的選擇,儘管我還沒有嘗試過。我強烈建議你給這些框架一個機會!它們將幫助你構建規範,優雅且設計良好的 REST API 服務。

總結

我們都應致力於讓呼叫 API 這件事成為一種樂趣。希望本文能使你瞭解到在構建更好的 REST API 服務的過程中,涉及到的一些建議和技巧。對我而言,應該把這些最佳實踐歸結為三點,分別是良好的語義,簡潔和合理性。

關注公眾號 全棧101,只談技術,不談人生

13 個設計 REST API 的最佳實踐

來源:https://juejin.im/post/5c1ba471f265da61257812bf#comment

相關文章