URL命名原则
- URL请求采用小写字母，数字，部分特殊符号（非制表符）组成。
- URL请求中不采用大小写混合的驼峰命名方式，尽量采用全小写单词，如果需要连接多个单词，则采用连接符“_”连接单词
-
query parameter可以采用驼峰命名法，也可以采用下划线命名的方式，推荐采用下划线命名的方式，据说后者比前者的识别度要高，其中，做前端开发基本都后者，而做服务器接口开发基本用前者
概念
常用 HTTP Methods
- GET：获取资源
- POST：创建资源
- PUT：更新资源全部属性
- PATCH: 用于资源的部分属性
幂等性
同一个RESTful接口的多次访问，得到的资源状态是相同的。
安全性
对该RESTful接口访问，不会使服务端资源的状态发生改变。
CRUD请求定义规范（用户和组织机构为例）
GET：(GET 用于获取和查询)
获取单个资源时，路由结构为 /资源复数/{资源ID}; 资源为不可数名词直接使用
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| GET | /users | 获取用户列表 | 是 | 是 |
| GET | /users/{id} | 获取指定用户 | 是 | 是 |
| GET | /orgs | 获取组织列表 | 是 | 是 |
| GET | /orgs/{id} | 获取指定组织 | 是 | 是 |
| GET | /orgs/{id}/users/{id} | 获取指定组织下的用户 | 是 | 是 |
POST:
只用于创建，路由结构为 /资源复数 ; 参数只能通过请求 Body 方式传参;
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| POST | /users | 创建用户 | 否 | 否 |
| POST | /orgs | 创建组织 | 否 | 否 |
PUT: (PUT 用于修改/更新资源)
路由结构为 /资源复数/{资源ID}, 只能通过 Body 方式传参
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| POST | /users/{id} | 更新用户 | 是 | 否 |
| POST | /orgs/{id} | 更新组织 | 是 | 否 |
PATCH: (PATCH 用于修改/更新资源部分属性)
路由结构为 /资源复数/{资源ID}, 只能通过 Body 方式传参
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| PATCH | /users/{id} | 更新用户部分属性 | 是 | 否 |
| PATCH | /orgs/{id} | 更新组织部分属性 | 是 | 否 |
DELETE：
删除接口使用， 路由结构为 /资源复数/{资源ID}
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| DELETE | /users/{id} | 删除指定用户 | 是 | 否 |
| DELETE | /orgs/{id} | 更新制定组织 | 是 | 否 |
复杂查询请求
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| GET | /users?locked=1 | 过滤被锁用户 | 是 | 是 |
| GET | /users?sort=priority | 按权重排序 | 是 | 是 |
| GET | /users?locked=1&sort=priority | 按权重排序 | 是 | 是 |
特定请求
资源的特定请求
采用在资源下面定义特定的请求pattern，见如下示例
| HTTP方法 | URI | 描述 | 幂等 | 安全 |
|---|---|---|---|---|
| GET | /users/today_login | 获取今天登入用户 | 是 | 是 |
| GET | /users/today_login?sort=loginTime | 获取今天登入用户按登入时间排序 | 是 | 是 |
| GET | /users/action/export | 导出所有用户 | 是 | 是 |
| PUT | /users/action/audit | 用户审核 | 是 | 是 |
| PATCH | /users/{id}/password | 用户修改密码 | 是 | 是 |
动作：/模块/资源/action/{action}
非特定资源类
请求URL采用如下形式: /login /logout
