RESTful API的十個最佳實踐

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

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

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

1. 使用名詞而不是動詞

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

不要使用動詞

<code>/getAllCars
/createNewCar
/deleteAllRedCars/<code>

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

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

<code>
GET
 
/users/711?activate or
GET
 
/users/711/activate
/<code>

3. 使用名詞的複數形式

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

<code>/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting/<code>

4. 為關係使用子資源

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

<code>GET 
/cars/711/drivers/
 Returns a list 
of
 drivers 
for
 car 
711
GET /cars/
711
/drivers/
4
 Returns driver /<code>

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

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

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

6. 使用HATEOAS

Hypermedia as the Engine of A

pplication State是一個指導原則，它規定超文本鏈接應該被用於在API中創建更好的資源導航：

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

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

過濾

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

<code>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/<code>

排序

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

<code>GET /cars?
sort
=-manufactorer,+model/<code>

字段選擇

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

<code>
GET
 /cars?fields=manufacturer,model,id,color/<code>

分頁

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

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

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

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

<code>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",/<code>

8. 版本化你的API

確保強制實行API版本，並且不要發佈一個沒有版本的API，使用簡單的序列數字，避免使用2.5.0這樣的形式：

<code>/blog/api/v1/<code>

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的模板：

<code>{
  
"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"
   }
  ]
} /<code>

10. 允許重寫HTTP方法

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

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