RESTful API的十個最佳實踐

WebAPI在過去幾年里非常的盛行，我們很多以往的技術手段都慢慢的轉換為使用WebAPI來開發，因為它的語法簡單規范化，以及輕量級等特點，這種方式收到了廣泛的推崇。

通常我們使用RESTFul（Representational State Transfer）的設計方式來設計Web api，這通常用來分離API結構了業務邏輯，它使用典型的HTTP方法，諸如GET,POST.DELETE,PUT來和資源進行交互。

以下是設計RESTful API的是個最佳實踐：

1. 使用名詞而不是動詞

為了易于理解，為資源使用下面的API結構：

不要使用動詞

/getAllCars
/createNewCar
/deleteAllRedCars

2. Get方法和查詢參數不應該改變資源狀態

使用Put,Post和Delete方法替代Get方法來改變資源狀態。不要使用Get來使狀態改變：

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

3. 使用名詞的復數形式

不要混合使用單數和復數形式，而應該為所有資源一直保持使用復數形式：

/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting

4. 為關系使用子資源

假如資源連接到其它資源，則使用子資源形式：

GET /cars/711/drivers/ Returns a list of drivers for car 711
GET /cars/711/drivers/4 Returns driver #4 for car 711

5. 使用HTTP頭決定序列化格式

在客戶端和服務端都需要知道使用什么格式來進行通信，這個格式應該在HTTP頭中指定:

• Content-Type：定義請求的格式；
• Accept ：定義允許的響應格式的列表

6. 使用HATEOAS

Hypermedia as the Engine of Application State是一個指導原則，它規定超文本鏈接應該被用于在API中創建更好的資源導航：

{
  "id": 711,
  "manufacturer": "bmw",
  "model": "X5",
  "seats": 5,
  "drivers": [
   {
    "id": "23",
    "name": "Stefan Jauker",
    "links": [
     {
     "rel": "self",
     "href": "/api/v1/drivers/23"
    }
   ]
  }
 ]
}

7. 為集合提供過濾、排序、字段選擇以及分頁

過濾

為所有字段或者查詢語句提供獨立的查詢參數：

GET /cars?color=red Returns a list of red cars
GET /cars?seats<=2 Returns a list of cars with a maximum of 2 seats

排序

允許跨越多字段的正序或者倒序排列：

GET /cars?sort=-manufactorer,+model

字段選擇

一些情況下，我們只需要在列表中查詢幾個有標識意義的字段，我們不需要從服務端把所有字段的值都請求出來，所以需要支持API選擇查詢字段的能力，這也可以提到網絡傳輸性能和速度：

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

分頁

使用offset和limit來獲取固定數量的資源結果，當其中一個參數沒有出現時，應該提供各自的默認值，比如默認取第一頁，或者默認取20條數據：

GET /cars?offset=10&limit=5
GET /cars?&limit=5  //Get first five result
GET /cars?&offset=5  //Get default amount result offset 5

使用自定義的頭X-Total-Count發回給調用段實際的資源數量。

前一頁后一頁的鏈接也應該在HTTP頭鏈接中得到支持，遵從下文中的鏈接原則而不要構建你自己的頭：

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.0這樣的形式：

/blog/api/v1

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

忽略錯誤處理的API是很難使用的，簡單的返回500和調用堆棧是非常不友好也非常無用的：

使用HTTP狀態碼

HTTP標準提供了70多個狀態碼來描述返回值，我們不需要完全用到他們，下文中列出10個使用率較高的：

200 – OK – 一切正常
201 – OK – 新資源已經被創建
204 – OK – 資源刪除成功

304 – 沒有變化，客戶端可以使用緩存數據

400 – Bad Request – 調用不合法，確切的錯誤應該在error payload中描述，例如：“JSON 不合法 ”
401 – 未認證，調用需要用戶通過認證
403 – 不允許的，服務端正常解析和請求，但是調用被回絕或者不被允許
404 – 未找到，指定的資源不存在
422 – 不可指定的請求體 – 只有服務器不能處理實體時使用，比如圖像不能被格式化，或者重要字段丟失。

500 – Internal Server Error – 標準服務端錯誤，API開發人員應該盡量避開這種錯誤

使用 error payloads

所有的異常都應該被映射到error payloads中，下文中的例子是一個json 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"
   }
  ]
} 

10. 允許重寫HTTP方法

一些代理只支持GET和POST方法，為了在這種限制下支持RESTful API，API需要重寫HTTP方法。

使用自定義的X-HTTP-Method-Override  HTTP頭來重寫POST方法。

來自：http://www.cnblogs.com/xiaoyaojian/p/4612503.html