URI 設(shè)計(jì)
GET /users/1
PUT /users/2
POST /users
DELETE /users/1
// 將某個(gè)用戶(hù)加入到某個(gè) Team 中
PUT /users/1?team_id=1
PUT /users/${user_id}?team_id=${team_id}
PUT /users/:user_id/team_id/:team_id
// 將某個(gè) Team 中的某個(gè)用戶(hù)設(shè)置為非激活狀態(tài)
PUT /term/1?user_id=1&status=inactive
PUT /term/:term_id/user_id/:user_id/inactive
// 訂閱欄目，表示訂閱用戶(hù)666的ID為1的項(xiàng)目，
POST /v1/users/1/projects/1/subscribe
// 收藏欄目，則將“收藏項(xiàng)目”這個(gè)動(dòng)作抽象為“給項(xiàng)目加一顆星”。
POST /v1/users/1/projects/1/star
GET /zoos：列出所有動(dòng)物園
POST /zoos：新建一個(gè)動(dòng)物園
GET /zoos/ID：獲取某個(gè)指定動(dòng)物園的信息
PUT /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的全部信息）
PATCH /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的部分信息）
DELETE /zoos/ID：刪除某個(gè)動(dòng)物園
GET /zoos/ID/animals：列出某個(gè)指定動(dòng)物園的所有動(dòng)物
DELETE /zoos/ID/animals/ID：刪除某個(gè)指定動(dòng)物園的指定動(dòng)物
// 復(fù)雜查詢(xún) 過(guò)濾信息(排序、分頁(yè)、篩選、搜索等)
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開(kāi)始位置。
?page=2&per_page=100：指定第幾頁(yè)，以及每頁(yè)的記錄數(shù)。
?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序。
?animal_type_id=1：指定篩選條件
冗余設(shè)計(jì)
主要是目錄層級(jí)、查詢(xún)、標(biāo)識(shí)之間的冗余
比如
/device/id/image/imgId
/image/imgId?deveci=id
參數(shù)的設(shè)計(jì)允許存在冗余，即允許API路徑和URL參數(shù)偶爾有重復(fù)。比如以下兩個(gè)請(qǐng)求含義相同
GET /zoo/:id/animals
GET /animals?zoo_id=:id
Header 頭設(shè)計(jì)
- 重寫(xiě)方法 - X-HTTP-Method-Override
- 版本 - Accept: vnd.example-com.foo+json; version=1.0
- 響應(yīng)類(lèi)型 - Accept: application/json Content-Type: application/json
- 緩存 -
- Expires: Mon, 11 Jun 2018 13:55:41 GMT
- Cache-Control: public, max-age=60
- 編碼 -
狀態(tài)碼設(shè)計(jì)
- 1xx：相關(guān)信息
- 2xx：操作成功
- 3xx：重定向
- 4xx：客戶(hù)端錯(cuò)誤
- 5xx：服務(wù)器錯(cuò)誤
200 OK - [GET]：服務(wù)器成功返回用戶(hù)請(qǐng)求的數(shù)據(jù)，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶(hù)新建或修改數(shù)據(jù)成功。
202 Accepted - []：表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）
204 NO CONTENT：無(wú)內(nèi)容。服務(wù)器成功處理，但未返回內(nèi)容
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶(hù)發(fā)出的請(qǐng)求有錯(cuò)誤，服務(wù)器沒(méi)有進(jìn)行新建或修改數(shù)據(jù)的操作，該操作是冪等的。
401 Unauthorized - []：表示用戶(hù)沒(méi)有權(quán)限（令牌、用戶(hù)名、密碼錯(cuò)誤）。
403 Forbidden - [] 表示用戶(hù)得到授權(quán)（與401錯(cuò)誤相對(duì)），但是訪(fǎng)問(wèn)是被禁止的。
404 NOT FOUND - []：用戶(hù)發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄，服務(wù)器沒(méi)有進(jìn)行操作，該操作是冪等的。
406 Not Acceptable - [GET]：用戶(hù)請(qǐng)求的格式不可得（比如用戶(hù)請(qǐng)求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用戶(hù)請(qǐng)求的資源被永久刪除，且不會(huì)再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯(cuò)誤，用戶(hù)將無(wú)法判斷發(fā)出的請(qǐng)求是否成功。
方法
| 方法名 | 介紹 |
|---|---|
| GET | 請(qǐng)求指定的頁(yè)面信息，并返回實(shí)體主體。 |
| HEAD | 類(lèi)似于 GET 請(qǐng)求，只不過(guò)返回的響應(yīng)中沒(méi)有具體的內(nèi)容，用于獲取報(bào)頭 |
| POST | 向指定資源提交數(shù)據(jù)進(jìn)行處理請(qǐng)求（例如提交表單或者上傳文件）。數(shù)據(jù)被包含在請(qǐng)求體中。POST 請(qǐng)求可能會(huì)導(dǎo)致新的資源的建立和/或已有資源的修改。 |
| PUT | 從客戶(hù)端向服務(wù)器傳送的數(shù)據(jù)取代指定的文檔的內(nèi)容。 |
| DELETE | 請(qǐng)求服務(wù)器刪除指定的頁(yè)面。 |
| CONNECT | HTTP/1.1 協(xié)議中預(yù)留給能夠?qū)⑦B接改為管道方式的代理服務(wù)器。 |
| OPTIONS | 允許客戶(hù)端查看服務(wù)器的性能。 |
| TRACE | 回顯服務(wù)器收到的請(qǐng)求，主要用于測(cè)試或診斷。 |
| PATCH | 是對(duì) PUT 方法的補(bǔ)充，用來(lái)對(duì)已知資源進(jìn)行局部更新 。 |
- GET：讀?。≧ead）
- POST：新建（Create）
- PUT：更新（Update）
- PATCH：更新（Update），通常是部分更新
- DELETE：刪除（Delete）
安全
- 冪等，重復(fù)提交
附錄
防重復(fù)提交
- 前端控制
- 后臺(tái)控制，使用鎖
- 后臺(tái)生成一個(gè)key供前端使用，后端再控制
參考
RESTful API URI 設(shè)計(jì): 查詢(xún)（Query）和標(biāo)識(shí)（Identify）
理解并設(shè)計(jì)rest/restful風(fēng)格接口
Restful api 防止重復(fù)提交
