[轉]10個有關RESTful API良好設計的最佳實踐

　Web API已經在最近幾年變成重要的話題，一個乾淨的API設計對於後端系統是很是重要的。

　　一般咱們爲Web API使用RESTful設計，REST概念分離了API結構和邏輯資源，經過Http方法GET, DELETE, POST 和 PUT來操做資源。

　　下面是進行RESTful Web API十個最佳實踐，能爲你提供一個良好的API設計風格。

 

1.使用名詞而不是動詞

Resource 資源	GET 讀	POST 建立	PUT 修改	DELETE
/cars	返回 cars集合	建立新的資源	批量更新cars	刪除全部cars
/cars/711	返回特定的car	該方法不容許(405)	更新一個指定的資源	擅長指定資源

不要使用：

/getAllCars
/createNewCar
/deleteAllRedCars

 

2.Get方法和查詢參數不該該涉及狀態改變

使用PUT, POST 和DELETE 方法 而不是 GET 方法來改變狀態，不要使用GET 進行狀態改變:

GET /users/711?activate 
GET /users/711/activate

 

3.使用複數名詞

不要混淆名詞單數和複數，爲了保持簡單，只對全部資源使用複數。

/cars 而不是 /car
/users 而不是 /user
/products 而不是 /product
/settings 而部署 /setting

 

4. 使用子資源表達關係

若是一個資源與另一個資源有關係，使用子資源：

GET /cars/711/drivers/ 返回 car 711的全部司機
GET /cars/711/drivers/4 返回 car 711的4號司機

 

5.使用Http頭聲明序列化格式

在客戶端和服務端，雙方都要知道通信的格式，格式在HTTP-Header中指定

Content-Type 定義請求格式
Accept 定義系列可接受的響應格式

 

6.使用HATEOAS

Hypermedia as the Engine of Application State 超媒體做爲應用狀態的引擎，超文本連接能夠創建更好的文本瀏覽：

{

  "id": 711,

  "manufacturer": "bmw",

  "model": "X5",

  "seats": 5,

  "drivers": [

   {

    "id": "23",

    "name": "Stefan Jauker",

    "links": [

     {

     "rel": "self",

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

    }

   ]

  }

 ]

}

注意href指向下一個URL

7.爲集合提供過濾 排序 選擇和分頁等功能

Filtering過濾:

使用惟一的查詢參數進行過濾：

GET /cars?color=red 返回紅色的cars
GET /cars?seats<=2 返回小於兩座位的cars集合

Sorting排序:

容許針對多個字段排序

GET /cars?sort=-manufactorer,+model

這是返回根據生產者降序和模型升序排列的car集合

Field selection

移動端可以顯示其中一些字段，它們其實不須要一個資源的全部字段，給API消費者一個選擇字段的能力，這會下降網絡流量，提升API可用性。

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

 

Paging分頁

使用 limit 和offset.實現分頁，缺省limit=20 和offset=0；

GET /cars?offset=10&limit=5

爲了將總數發給客戶端，使用訂製的HTTP頭： X-Total-Count.

連接到下一頁或上一頁能夠在HTTP頭的link規定，遵循Link規定:

Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",

 

8.版本化你的API

使得API版本變得強制性，不要發佈無版本的API，使用簡單數字，避免小數點如2.5.

通常在Url後面使用?v

/blog/api/v1

 

9. 使用Http狀態碼處理錯誤

若是你的API沒有錯誤處理是很難的，只是返回500和出錯堆棧不必定有用

Http狀態碼提供70個出錯，咱們只要使用10個左右：

200 – OK – 一切正常
201 – OK – 新的資源已經成功建立
204 – OK – 資源已經成功擅長

304 – Not Modified – 客戶端使用緩存數據

400 – Bad Request – 請求無效，須要附加細節解釋如 "JSON無效"
401 – Unauthorized – 請求須要用戶驗證
403 – Forbidden – 服務器已經理解了請求，可是拒絕服務或這種請求的訪問是不容許的。
404 – Not found – 沒有發現該資源
422 – Unprocessable Entity – 只有服務器不能處理實體時使用，好比圖像不能被格式化，或者重要字段丟失。

500 – Internal Server Error – API開發者應該避免這種錯誤。

使用詳細的錯誤包裝錯誤：

{

  "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"

   }

  ]

}

10.容許覆蓋http方法

一些代理只支持POST 和 GET方法， 爲了使用這些有限方法支持RESTful API，須要一種辦法覆蓋http原來的方法。

使用訂製的HTTP頭 X-HTTP-Method-Override 來覆蓋POST 方法.