如何優雅的設計RESTful API？這是我看過講的最清晰的文章！

RESTful 是目前最流行的 API 設計規範，用於 Web 數據接口的設計。它的大原則容易把握，可是細節不容易作對。

本文總結 RESTful 的設計細節，介紹如何設計出易於理解和使用的 API。

1、URL 設計

1.1 動詞 + 賓語

RESTful 的核心思想就是，客戶端發出的數據操做指令都是"動詞 + 賓語"的結構。

好比，GET /articles這個命令，GET是動詞，/articles是賓語。動詞一般就是五種 HTTP 方法，對應 CRUD 操做。

• GET：讀取（Read）

• POST：新建（Create）

• PUT：更新（Update）

• PATCH：更新（Update），一般是部分更新

• DELETE：刪除（Delete）

根據 HTTP 規範，動詞一概大寫。

1.2 動詞的覆蓋

有些客戶端只能使用GET和POST這兩種方法，服務器必須接受POST模擬其餘三個方法（PUT、PATCH、DELETE）

這時，客戶端發出的 HTTP 請求，要加上X-HTTP-Method-Override屬性，告訴服務器應該使用哪個動詞，覆蓋POST方法。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT
複製代碼

上面代碼中，X-HTTP-Method-Override 指定本次請求的方法是PUT，而不是POST。

1.3 賓語必須是名詞

賓語就是 API 的 URL，是 HTTP 動詞做用的對象。它應該是名詞，不能是動詞。

好比，/articles這個 URL 就是正確的，而下面的 URL 不是名詞，因此都是錯誤的。

• /getAllCars

• /createNewCar

• /deleteAllRedCars

1.4 複數 URL

既然 URL 是名詞，那麼應該使用複數，仍是單數？這沒有統一的規定，可是常見的操做是讀取一個集合。

好比GET /articles（讀取全部文章），這裏明顯應該是複數。

爲了統一塊兒見，建議都使用複數 URL，好比GET /articles/2要好於GET /article/2。

1.5 避免多級 URL

常見的狀況是，資源須要多級分類，所以很容易寫出多級的 URL，好比獲取某個做者的某一類文章。

GET /authors/12/categories/2複製代碼

這種 URL 不利於擴展，語義也不明確，每每要想一會，才能明白含義。

更好的作法是，除了第一級，其餘級別都用查詢字符串表達。

GET /authors/12?categories=2複製代碼

下面是另外一個例子，查詢已發佈的文章。你可能會設計成下面的 URL。

GET /articles/published複製代碼

查詢字符串的寫法明顯更好。

GET /articles?published=true
複製代碼

2、狀態碼

2.1 狀態碼必須精確

客戶端的每一次請求，服務器都必須給出迴應。迴應包括 HTTP 狀態碼和數據兩部分。

HTTP 狀態碼就是一個三位數，分紅五個類別。

• 1xx：相關信息

• 2xx：操做成功

• 3xx：重定向

• 4xx：客戶端錯誤

• 5xx：服務器錯誤

這五大類總共包含100多種狀態碼，覆蓋了絕大部分可能遇到的狀況。

每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需查看狀態碼，就能夠判斷出發生了什麼狀況，因此服務器應該返回儘量精確的狀態碼。

API 不須要1xx狀態碼，下面介紹其餘四類狀態碼的精確含義。

2.2 2xx 狀態碼

200狀態碼錶示操做成功，可是不一樣的方法能夠返回更精確的狀態碼。

• GET: 200 OK

• POST: 201 Created

• PUT: 200 OK

• PATCH: 200 OK

• DELETE: 204 No Content

上面代碼中，POST返回201狀態碼，表示生成了新的資源；DELETE返回204狀態碼，表示資源已經不存在。

此外，202 Accepted狀態碼錶示服務器已經收到請求，但還未進行處理，會在將來再處理，一般用於異步操做。

下面是一個例子。

HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}
複製代碼

2.3 3xx 狀態碼

API 用不到301狀態碼（永久重定向）和302狀態碼（暫時重定向，307也是這個含義）

由於它們能夠由應用級別返回，瀏覽器會直接跳轉，API 級別能夠不考慮這兩種狀況。

API 用到的3xx狀態碼，主要是303 See Other，表示參考另外一個 URL。

它與302和307的含義同樣，也是"暫時重定向"，區別在於302和307用於GET請求，而303用於POST、PUT和DELETE請求。

收到303之後，瀏覽器不會自動跳轉，而會讓用戶本身決定下一步怎麼辦。

下面是一個例子。

HTTP/1.1 303 See Other
Location: /api/orders/12345複製代碼

2.4 4xx 狀態碼

4xx狀態碼錶示客戶端錯誤，主要有下面幾種：

• 400 Bad Request：服務器不理解客戶端的請求，未作任何處理

• 401 Unauthorized：用戶未提供身份驗證憑據，或者沒有經過身份驗證

• 403 Forbidden：用戶經過了身份驗證，可是不具備訪問資源所需的權限

• 404 Not Found：所請求的資源不存在，或不可用

• 405 Method Not Allowed：用戶已經經過身份驗證，可是所用的 HTTP 方法不在他的權限以內

• 410 Gone：所請求的資源已從這個地址轉移，再也不可用

• 415 Unsupported Media Type：客戶端要求的返回格式不支持。好比，API 只能返回 JSON 格式，可是客戶端要求返回 XML 格式

• 422 Unprocessable Entity ：客戶端上傳的附件沒法處理，致使請求失敗

• 429 Too Many Requests：客戶端的請求次數超過限額。

2.5 5xx 狀態碼

5xx狀態碼錶示服務端錯誤。通常來講，API 不會向用戶透露服務器的詳細信息，因此只要兩個狀態碼就夠了。

• 500 Internal Server Error：客戶端請求有效，服務器處理時發生了意外

• 503 Service Unavailable：服務器沒法處理請求，通常用於網站維護狀態

3、服務器迴應

3.1 不要返回純本文

API 返回的數據格式，不該該是純文本，而應該是一個 JSON 對象，由於這樣才能返回標準的結構化數據。

因此，服務器迴應的 HTTP 頭的Content-Type屬性要設爲application/json。

客戶端請求時，也要明確告訴服務器，能夠接受 JSON 格式，即請求的 HTTP 頭的ACCEPT屬性也要設成application/json。

下面是一個例子。

GET /orders/2 HTTP/1.1 
Accept: application/json
複製代碼

3.2 發生錯誤時，不要返回 200 狀態碼

有一種不恰當的作法是，即便發生錯誤，也返回200狀態碼，把錯誤信息放在數據體裏面，就像下面這樣。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}
複製代碼

上面代碼中，解析數據體之後，才能得知操做失敗。

這張作法實際上取消了狀態碼，這是徹底不可取的。正確的作法是，狀態碼反映發生的錯誤，具體的錯誤信息放在數據體裏面返回。

下面是一個例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json

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

3.3 提供連接

API 的使用者未必知道，URL 是怎麼設計的。一個解決方法就是，在迴應中，給出相關連接，便於下一步操做。

這樣的話，用戶只要記住一個 URL，就能夠發現其餘的 URL。這種方法叫作 HATEOAS。

舉例來講，GitHub 的 API 都在 api.github.com 這個域名。訪問它，就能夠獲得其餘 URL。

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}複製代碼

上面的迴應中，挑一個 URL 訪問，又能夠獲得別的 URL。對於用戶來講，不須要記住 URL 設計，只要從 api.github.com 一步步查找就能夠了。

HATEOAS 的格式沒有統一規定，上面例子中，GitHub 將它們與其餘屬性放在一塊兒。更好的作法應該是，將相關連接與其餘屬性分開。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}複製代碼

End

做者：阮一峯

來源：

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html

本文版權歸做者全部

長按下圖二維碼，即刻關注【狸貓技術窩】 

阿里、京東、美團、字節跳動 頂尖技術專家坐鎮 

爲IT人打造一個 「有溫度」 的技術窩！