URL命名原則
- URL請(qǐng)求采用小寫字母，數(shù)字，部分特殊符號(hào)（非制表符）組成。
- URL請(qǐng)求中不采用大小寫混合的駝峰命名方式，盡量采用全小寫單詞，如果需要連接多個(gè)單詞，則采用連接符“_”連接單詞
-
query parameter可以采用駝峰命名法，也可以采用下劃線命名的方式，推薦采用下劃線命名的方式，據(jù)說(shuō)后者比前者的識(shí)別度要高，其中，做前端開(kāi)發(fā)基本都后者，而做服務(wù)器接口開(kāi)發(fā)基本用前者
概念
常用 HTTP Methods
- GET：獲取資源
- POST：創(chuàng)建資源
- PUT：更新資源全部屬性
- PATCH: 用于資源的部分屬性
冪等性
同一個(gè)RESTful接口的多次訪問(wèn)，得到的資源狀態(tài)是相同的。
安全性
對(duì)該RESTful接口訪問(wèn)，不會(huì)使服務(wù)端資源的狀態(tài)發(fā)生改變。
CRUD請(qǐng)求定義規(guī)范（用戶和組織機(jī)構(gòu)為例）
GET：(GET 用于獲取和查詢)
獲取單個(gè)資源時(shí)，路由結(jié)構(gòu)為 /資源復(fù)數(shù)/{資源ID}; 資源為不可數(shù)名詞直接使用
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| GET | /users | 獲取用戶列表 | 是 | 是 |
| GET | /users/{id} | 獲取指定用戶 | 是 | 是 |
| GET | /orgs | 獲取組織列表 | 是 | 是 |
| GET | /orgs/{id} | 獲取指定組織 | 是 | 是 |
| GET | /orgs/{id}/users/{id} | 獲取指定組織下的用戶 | 是 | 是 |
POST:
只用于創(chuàng)建，路由結(jié)構(gòu)為 /資源復(fù)數(shù) ; 參數(shù)只能通過(guò)請(qǐng)求 Body 方式傳參;
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| POST | /users | 創(chuàng)建用戶 | 否 | 否 |
| POST | /orgs | 創(chuàng)建組織 | 否 | 否 |
PUT: (PUT 用于修改/更新資源)
路由結(jié)構(gòu)為 /資源復(fù)數(shù)/{資源ID}, 只能通過(guò) Body 方式傳參
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| POST | /users/{id} | 更新用戶 | 是 | 否 |
| POST | /orgs/{id} | 更新組織 | 是 | 否 |
PATCH: (PATCH 用于修改/更新資源部分屬性)
路由結(jié)構(gòu)為 /資源復(fù)數(shù)/{資源ID}, 只能通過(guò) Body 方式傳參
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| PATCH | /users/{id} | 更新用戶部分屬性 | 是 | 否 |
| PATCH | /orgs/{id} | 更新組織部分屬性 | 是 | 否 |
DELETE：
刪除接口使用， 路由結(jié)構(gòu)為 /資源復(fù)數(shù)/{資源ID}
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| DELETE | /users/{id} | 刪除指定用戶 | 是 | 否 |
| DELETE | /orgs/{id} | 更新制定組織 | 是 | 否 |
復(fù)雜查詢請(qǐng)求
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| GET | /users?locked=1 | 過(guò)濾被鎖用戶 | 是 | 是 |
| GET | /users?sort=priority | 按權(quán)重排序 | 是 | 是 |
| GET | /users?locked=1&sort=priority | 按權(quán)重排序 | 是 | 是 |
特定請(qǐng)求
資源的特定請(qǐng)求
采用在資源下面定義特定的請(qǐng)求pattern，見(jiàn)如下示例
| HTTP方法 | URI | 描述 | 冪等 | 安全 |
|---|---|---|---|---|
| GET | /users/today_login | 獲取今天登入用戶 | 是 | 是 |
| GET | /users/today_login?sort=loginTime | 獲取今天登入用戶按登入時(shí)間排序 | 是 | 是 |
| GET | /users/action/export | 導(dǎo)出所有用戶 | 是 | 是 |
| PUT | /users/action/audit | 用戶審核 | 是 | 是 |
| PATCH | /users/{id}/password | 用戶修改密碼 | 是 | 是 |
動(dòng)作：/模塊/資源/action/{action}
非特定資源類
請(qǐng)求URL采用如下形式: /login /logout
