寫在前面
之所以翻譯這篇文章，是因為自從成為一名前端碼農之后，調接口這件事情就成為了家常便飯，並且，還伴隨着無數的爭論與無奈。編寫友好的 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 服務的過程中，涉及到的一些建議和技巧。對我而言，應該把這些最佳實踐歸結為三點，分別是良好的語義，簡潔和合理性。
PS：分析一個好消息
同學，你造嗎？阿里雲和騰訊雲已白菜價，最新活動，雲服務器低至不到300元/年。這里有一份雲計算優惠活動列表，來不及解釋了，趕緊上車！
作者：HaoliangWu
鏈接：https://juejin.im/post/5c1ba471f265da61257812bf