轉(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ī)范
- 不用大寫(xiě);
- 用中杠-不用下杠_;
- 參數(shù)列表要encode;
- URI中的名詞表示資源集合傻丝，使用復(fù)數(shù)形式葫男。
資源集合 vs 單個(gè)資源
URI表示資源的兩種方式：資源集合翅萤、單個(gè)資源窒盐。
- 資源集合：
/zoos //所有動(dòng)物園
/zoos/1/animals //id為1的動(dòng)物園中的所有動(dòng)物
- 單個(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à)的。
| 安全性 | 冪等性 | |
|---|---|---|
| get | √ | √ |
| post | × | × |
| put | × | √ |
| delete | × | √ |
安全性和冪等性均不保證反復(fù)請(qǐng)求能拿到相同的response铜靶。以 DELETE 為例叔遂，第一次DELETE返回200表示刪除成功，第二次返回404提示資源不存在，這是允許的已艰。
復(fù)雜查詢
查詢可以捎帶以下參數(shù)：
| 實(shí)例 | 備注 | |
|---|---|---|
| 過(guò)濾條件 | ?type=1&age=16 | 允許一定的uri冗余痊末，如/zoos/1與/zoos?id=1 |
| 排序 | ?sort=age,desc | |
| 投影 | ?whitelist=id,name,email | |
| 分頁(yè) | ?limit=10&offset=3 |
Format
只用以下常見(jiàn)的3種body format：
- 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"
}
- 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
- multipart/form-data; boundary=----WebKitFormBoundaryITio08aDVqufJd9L(表單有文件上傳時(shí)的格式)
Content Negotiation
資源可以有多種表示方式凿叠，如json、xml嚼吞、pdf盒件、excel等等，客戶端可以指定自己期望的格式舱禽，通常有兩種方式：
- http header Accept：
Accept:application/xml;q=0.6,application/atom+xml;q=1.0 - uri中加文件后綴
/zoo/1.json
Response
- 不要包裝：
response 的 body 直接就是數(shù)據(jù)履恩，不要做多余的包裝。錯(cuò)誤示例：
{
"success":true,
"data":{"id":1,"name":"xiaotuan"},
}
正確示例:
{
"id":1,
"name":"xiaotuan"
}
- 各HTTP方法成功處理后的數(shù)據(jù)格式
| response 格式 | |
|---|---|
| GET | 單個(gè)對(duì)象呢蔫、集合 |
| POST | 新增成功的對(duì)象 |
| PUT/PATCH | 更新成功的對(duì)象 |
| DELETE | 空 |
