轉(zhuǎn)自：http://blog.csdn.net/yue7603835/article/details/52536497

URI

URI （Uniform Resource Identifier，統(tǒng)一資源標(biāo)識(shí)符)，資源一般對(duì)應(yīng)服務(wù)器端領(lǐng)域模型中的實(shí)體類。

URI規(guī)范

1. 不用大寫;
2. 用中杠-不用下杠_;
3. 參數(shù)列表要encode;
4. URI中的名詞表示資源集合，使用復(fù)數(shù)形式。

資源集合 vs 單個(gè)資源

URI表示資源的兩種方式：資源集合、單個(gè)資源。

1. 資源集合：

/zoos //所有動(dòng)物園
/zoos/1/animals //id為1的動(dòng)物園中的所有動(dòng)物

2. 單個(gè)資源：

/zoos/1 //id為1的動(dòng)物園
/zoos/1;2;3 //id為1，2，3的動(dòng)物園

避免層級(jí)過(guò)深的URI

/在uri中表達(dá)層級(jí)，用于按實(shí)體關(guān)聯(lián)關(guān)系進(jìn)行對(duì)象導(dǎo)航，一般根據(jù)id導(dǎo)航。
過(guò)深的導(dǎo)航容易導(dǎo)致uri膨脹，不易維護(hù)，如:
GET /zoos/1/areas/3/animals/4。
盡量使用查詢參數(shù)代替路徑中的實(shí)體導(dǎo)航，如:
GET /animals?zoo=1&area=3；

對(duì)Composite資源的訪問(wèn)

服務(wù)器端的組合實(shí)體必須在uri中通過(guò)父實(shí)體的id導(dǎo)航訪問(wèn)。
組合實(shí)體不是first-class的實(shí)體，它的生命周期完全依賴父實(shí)體，它是無(wú)法獨(dú)立存在的，在實(shí)現(xiàn)上通常是對(duì)數(shù)據(jù)庫(kù)表中某些列的抽象，不直接對(duì)應(yīng)表，也無(wú)id。一個(gè)常見(jiàn)的例子是 User — Address，Address是對(duì)User表中zipCode，country，city三個(gè)字段的簡(jiǎn)單抽象，無(wú)法獨(dú)立于User存在。必須通過(guò)User索引到Address：

GET /user/1/addresses    //id為1的用戶的地址

Request

HTTP方法

通過(guò)標(biāo)準(zhǔn)HTTP方法對(duì)資源CRUD：
GET：查詢

GET /zoos    //查詢所有動(dòng)物園
GET /zoos/1    //查詢id為1的動(dòng)物園
GET /zoos/1/employees    //查詢id為1的動(dòng)物園的所有員工
GET /zoos/1/employees/1    //查詢id為1的動(dòng)物園的1號(hào)員工

POST：創(chuàng)建單個(gè)資源。POST一般向“資源集合”型uri發(fā)起

POST /animals  //新增動(dòng)物
POST /zoos/1/employees //為id為1的動(dòng)物園雇傭員工

PUT：更新單個(gè)資源（全量），客戶端提供完整的更新后的資源。與之對(duì)應(yīng)的是 PATCH，PATCH 負(fù)責(zé)部分更新，客戶端提供要更新的那些字段。PUT/PATCH一般向“單個(gè)資源”型uri發(fā)起

PUT /animals/1
PUT /zoos/1

DELETE：刪除

DELETE /zoos/1/employees/2    //刪除id為1的動(dòng)物園的2號(hào)員工
DELETE /zoos/1/employees/2;4;5    //刪除id為1的動(dòng)物園的2,4,5號(hào)員工
DELETE /zoos/1/animals  //刪除id為1的動(dòng)物園內(nèi)的所有動(dòng)物

安全性和冪等性

安全性：不會(huì)改變資源狀態(tài)，可以理解為只讀的；
冪等性：執(zhí)行1次和執(zhí)行N次，對(duì)資源狀態(tài)改變的效果是等價(jià)的。

安全性和冪等性均不保證反復(fù)請(qǐng)求能拿到相同的response。以 DELETE 為例，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的。

復(fù)雜查詢

查詢可以捎帶以下參數(shù)：

Format

只用以下常見(jiàn)的3種body format：

1. Content-Type: application/json；spring mvc用@RequestBody解析成對(duì)象

POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24

{
  "name": "Gir",
  "animalType": "12"
}

2. Content-Type: application/x-www-form-urlencoded (瀏覽器POST表單用的格式，@RequestBody不能解析)

POST /login HTTP/1.1
Host: example.com
Content-Length: 31
Accept: text/html
Content-Type: application/x-www-form-urlencoded

username=root&password=Zion0101

3. multipart/form-data; boundary=----WebKitFormBoundaryITio08aDVqufJd9L(表單有文件上傳時(shí)的格式)

Content Negotiation

資源可以有多種表示方式，如json、xml、pdf、excel等等，客戶端可以指定自己期望的格式，通常有兩種方式：

1. http header Accept：
   Accept:application/xml;q=0.6,application/atom+xml;q=1.0
2. uri中加文件后綴
   /zoo/1.json

Response

1. 不要包裝：
   response 的 body 直接就是數(shù)據(jù)，不要做多余的包裝。錯(cuò)誤示例：

{
    "success":true,
    "data":{"id":1,"name":"xiaotuan"},
}

正確示例:

{
  "id":1,
  "name":"xiaotuan"
}

2. 各HTTP方法成功處理后的數(shù)據(jù)格式