RESTful API的十個最佳實踐 - 小白哥哥 - 博客園
WebAPI在過去幾年里非常的盛行，我們很多以往的技術手段都慢慢的轉(zhuǎn)換為使用WebAPI來開發(fā)催烘，因為它的語法簡單規(guī)范化遥赚，以及輕量級等特點唯绍，這種方式收到了廣泛的推崇蛉腌。
通常我們使用RESTFul（Representational State Transfer）的設計方式來設計Web api肉拓，這通常用來分離API結(jié)構(gòu)了業(yè)務邏輯，它使用典型的HTTP方法竞穷，諸如GET,POST.DELETE,PUT來和資源進行交互唐责。
以下是設計RESTful API的是個最佳實踐：
1. 使用名詞而不是動詞
為了易于理解，為資源使用下面的API結(jié)構(gòu)：
Resource ?Get
read
Post
create
Put
update
Delete
/cars返回一個car的列表創(chuàng)建一個新的car更新car的信息刪除所有的car
/cars/2返回指定的carMethod not allowed(405)更新指定的car的信息刪除指定的car
不要使用動詞
/getAllCars
/createNewCar
/deleteAllRedCars
2. Get方法和查詢參數(shù)不應該改變資源狀態(tài)
使用Put,Post和Delete方法替代Get方法來改變資源狀態(tài)瘾带。不要使用Get來使狀態(tài)改變：
GET /users/711?activate or
GET /users/711/activate
3. 使用名詞的復數(shù)形式
不要混合使用單數(shù)和復數(shù)形式鼠哥，而應該為所有資源一直保持使用復數(shù)形式：
/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是一個指導原則抄罕，它規(guī)定超文本鏈接應該被用于在API中創(chuàng)建更好的資源導航：
{
? "id": 711,
? "manufacturer": "bmw",
? "model": "X5",
? "seats": 5,
? "drivers": [
? {
? ? "id": "23",
? ? "name": "Stefan Jauker",
? ? "links": [
? ? {
? ? "rel": "self",
? ? "href": "/api/v1/drivers/23"? ? }
? ]
? }
]
}
7. 為集合提供過濾、排序于颖、字段選擇以及分頁
過濾
為所有字段或者查詢語句提供獨立的查詢參數(shù)：
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選擇查詢字段的能力做入，這也可以提到網(wǎng)絡傳輸性能和速度：
GET /cars?fields=manufacturer,model,id,color
分頁
使用offset和limit來獲取固定數(shù)量的資源結(jié)果，當其中一個參數(shù)沒有出現(xiàn)時同衣，應該提供各自的默認值竟块，比如默認取第一頁，或者默認取20條數(shù)據(jù)：
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發(fā)回給調(diào)用段實際的資源數(shù)量耐齐。
前一頁后一頁的鏈接也應該在HTTP頭鏈接中得到支持浪秘，遵從下文中的鏈接原則而不要構(gòu)建你自己的頭：
Link:; rel="next",; rel="last",; rel="first",; rel="prev",
8. 版本化你的API
確保強制實行API版本，并且不要發(fā)布一個沒有版本的API埠况，使用簡單的序列數(shù)字耸携，避免使用2.5.0這樣的形式：
/blog/api/v1
9. 使用HTTP狀態(tài)碼處理錯誤
忽略錯誤處理的API是很難使用的，簡單的返回500和調(diào)用堆棧是非常不友好也非常無用的：
使用HTTP狀態(tài)碼
HTTP標準提供了70多個狀態(tài)碼來描述返回值辕翰，我們不需要完全用到他們夺衍，下文中列出10個使用率較高的：
200 – OK – 一切正常
201 – OK – 新資源已經(jīng)被創(chuàng)建
204 – OK – 資源刪除成功
304 – 沒有變化隙券，客戶端可以使用緩存數(shù)據(jù)
400 – Bad Request – 調(diào)用不合法块差，確切的錯誤應該在error payload中描述，例如：“JSON 不合法 ”
401 – 未認證硫眨，調(diào)用需要用戶通過認證
403 – 不允許的渊抄，服務端正常解析和請求尝胆，但是調(diào)用被回絕或者不被允許
404 – 未找到，指定的資源不存在
422 – 不可指定的請求體 – 只有服務器不能處理實體時使用护桦，比如圖像不能被格式化含衔，或者重要字段丟失。
500 – Internal Server Error – 標準服務端錯誤二庵，API開發(fā)人員應該盡量避開這種錯誤
使用 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方法。
