原文 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 中包含動詞（或方法）： GET、POST、PUT、PATCH 還有 DELETE 是最常用的。
• REST 是面向資源的，一個資源被一個 URI 所標識，比如 /articles/。
• 端點（endpoint），一般指動詞與 URI 的組合，比如 GET: /articles/
  。
• 一個端點可以被解釋為對某種資源進行的某個動作。比如， POST: /articles 可能代表“建立一個新的 article”。
• 在業務領域，我們常常可以將動詞和 CRUD（增刪查改）關聯起來：GET 代表查，POST代表增，PUT 和 PATCH 代表改（注: 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 OK
Content-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 Request
Content-Type: application/json

{
    "error": "Expected at least two items in list."
}
複製程式碼

7. 保持 status code 的一致性

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

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

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

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content
複製程式碼

blog.florimondmanca.com/restful-api…

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 來完成篩選和分頁功能

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

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

• 篩選：使用者可以提供額外的屬性來控制返回的資料集合
• 分頁：獲取資料集合的子集，最簡單的分頁是基於分頁個數的分頁，它由 page 和 page_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，只談技術，不談人生