RESTful API 設計最佳實踐

Web API 近幾年變得愈來愈火，而簡潔的 API 設計在多後端系統交互應用中也變得尤其重要。一般，會使用 RESTful API 來做爲咱們的 Web API 。本文介紹了幾種簡潔 RESTful API 設計的最佳實踐。

使用的名詞而不是動詞

使用名詞來定義接口

不該該使用動詞：

/getAllResources

/createNewResource

/deleteAllResources

GET 方法和查詢參數不能改變資源狀態

若是要改變資源的狀態，使用 PUT, POST 和 DELETE。下面是錯誤的用 GET 方法來修改 user 的狀態：

GET /users/711?activate 或

GET /users/711/activate

使用名詞複數

不要混淆名詞的單複數。保持簡單，只用複數名詞定義全部資源。

/cars 代替 /car

/users 代替 /user

/products 代替 /product

/settings 代替 /setting

使用子資源來表達資源間的關係

GET /cars/711/drivers/  返回 711 號 car 的全部 driver 列表

GET /cars/711/drivers/4 返回 711 號 car 的 4 號 driver

使用 HTTP header 來序列化格式

客戶端、服務端都須要知道互相之間的通信格式。這些格式能夠定義在 HTTP header 裏面：

• Content-Type：定義了請求格式

• Accept：定義了接收相應的格式列表

使用 HATEOAS 約束

HATEOAS（Hypermedia as the engine of application state）是 REST 架構風格中最複雜的約束，也是構建成熟 REST 服務的核心。它的重要性在於打破了客戶端和服務器之間嚴格的契約，使得客戶端能夠更加智能和自適應，而 REST 服務自己的演化和更新也變得更加容易。 在介紹 HATEOAS 以前，先介紹一下 Richardson 提出的 REST 成熟度模型。該模型把 REST 服務按照成熟度劃分紅 4 個層次：

• 第一個層次（Level 0）的 Web 服務只是使用 HTTP 做爲傳輸方式，實際上只是遠程方法調用（RPC）的一種具體形式。SOAP 和 XML-RPC 都屬於此類。

• 第二個層次（Level 1）的 Web 服務引入了資源的概念。每一個資源有對應的標識符和表達。

• 第三個層次（Level 2）的 Web 服務使用不一樣的 HTTP 方法來進行不一樣的操做，而且使用 HTTP 狀態碼來表示不一樣的結果。如 HTTP GET 方法來獲取資源，HTTP DELETE 方法來刪除資源。

• 第四個層次（Level 3）的 Web 服務使用 HATEOAS。在資源的表達中包含了連接信息。客戶端能夠根據連接來發現能夠執行的動做。

從上述 REST 成熟度模型中能夠看到，使用 HATEOAS 的 REST 服務是成熟度最高的，也是推薦的作法。對於不使用 HATEOAS 的 REST 服務，客戶端和服務器的實現之間是緊密耦合的。客戶端須要根據服務器提供的相關文檔來了解所暴露的資源和對應的操做。當服務器發生了變化時，如修改了資源的 URI，客戶端也須要進行相應的修改。而使用 HATEOAS 的 REST 服務中，客戶端能夠經過服務器提供的資源的表達來智能地發現能夠執行的操做。當服務器發生了變化時，客戶端並不須要作出修改，由於資源的 URI 和其餘信息都是動態發現的。

下面是一個 HATEOAS 的例子：

{

  "id": 711,

  "manufacturer": "bmw",

  "model": "X5",

  "seats": 5,

  "drivers": [

   {

    "id": "23",

    "name": "Stefan Jauker",

    "links": [

     {

     "rel": "self",

     "href": "/api/v1/drivers/23"

    }

   ]

  }

 ]

}

提供過濾、排序、字段選擇、分頁

過濾：

GET /cars?color=red 

GET /cars?seats<=2

排序：

GET /cars?sort=-manufactorer,+model

字段選擇:

GET /cars?fields=manufacturer,model,id,color

分頁:

GET /cars?offset=10&limit=5

API 版本化

版本號使用簡單的序號，並避免點符號，如2.5等。正確用法以下：

/blog/api/v1

充分使用 HTTP 狀態碼來處理錯誤

HTTP狀態碼（HTTP Status Code）是用以表示網頁服務器 HTTP 響應狀態的3位數字代碼。它由 RFC 2616 規範定義的，並獲得 RFC 251八、RFC 281七、RFC 229五、RFC 277四、RFC 4918 等規範的擴展。

在設計 API 處理錯誤時，應該充分使用 HTTP 狀態碼，而不是簡單的拋出個 「500 – Internal Server Error（內部服務器錯誤）」

全部的異常都應該有個錯誤的 payload 做爲映射，下面是一個例子：

{

  "errors": [

   {

    "userMessage": "Sorry, the requested resource does not exist",

    "internalMessage": "No car found in the database",

    "code": 34,

    "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"

   }

  ]

}

            來源：waylau，waylau.com/best-practices-for-better-restful-api/

參考引用

• 《REST 實戰》

• http://martinfowler.com/articles/richardsonMaturityModel.html

• https://www.crummy.com/writing/speaking/2008-QCon/act3.html

• https://en.wikipedia.org/wiki/HATEOAS

• https://en.wikipedia.org/wiki/List_of_HTTP_status_codes