RESTful API规则说明
RESTful 架构简介
- 每一个 URI 代表一种资源
- 客户端和服务器之间，传递这种资源的某种表现层
- 客户端通过四个 HTTP 动词，对服务器资源进行操作，实现“表现层状态转化”
协议
RESTful API 与用户的通讯协议，大多使用 https 或者 http 协议。
版本
默认 API 版本为 V1，默认的版本号不放入 URL，但未来由于接口变更，可能导致 URL 发生变更，为了便于接口版本管理，将会考虑在 URL 中加入版本号。
增加版本号的规则如下：
http://example.com/docs // v1版本的url
http://example.com/v2/docs // v2版本的url
路径(接口命名)
路径又称为“终点”，表示 API 的具体网址。
在 RESTful 架构中，每个网址代表一种资源，所以网址中不允许带有动词，只能有名词。
我们有个 API 接口用来提供产品信息，包括所有产品种类，价格等，正确的 API 设计应该如下：
GET /products 获取所有产品
POST /products 新建一个产品
GET /products/id 获取某个指定产品的信息
PUT /products/id 更新指定产品的信息
DELETE /products/id 删除指定产品信息
HTTP 方法
对于资源的具体操作类型，由 HTTP 方法名表示。
常用的 Http 方法主要有以下几种：
- GET 通过应用服务获取资源
- POST 通过应用服务新建资源
- PUT 通过应用服务更新资源
- DELETE 通过应用服务删除资源
过滤信息
过滤信息是指当通过应用服务一次性获取资源记录数量较多，需要加以限制返回的数据结果记录时，需要通过客户端在 API 中提供的参数，对返回结果进行过滤，这就是对应的查询操作。
对于上述获取产品的 API 中，可能存在以下过滤条件：
- 页码及数据记录行数：
?page=0&size=10,指定返回结果从第一页开始，每页记录为 10 条 - 排序：
?sort=price_des,指定按照价格降序排列返回结果 - 筛选条件：
?growArea=上海，只返回所有产品中产地为上海的数据记录
以上查询条件可以组合使用。
新 OA 中的过滤信息
- 页码及数据记录行数：
?page=0&size=15,指定返回结果从第一页开始，每页记录为 15 条 - 排序：
?sort=cjsj,ddsj_d，指定排序的第一字段为 cjsj(创建时间)且为升序排列，如果 cjsj 相等，则按 ddsj(到达时间)排序且排序方式为倒序排序 - 筛选条件：
?bt=123&cjsj=2019-05-15&zbbm=部门1，指定返回的数据记录必须同时满足的条件是 bt(标题)，cjsj(创建时间)，zbbm(主办部门)
数据传递格式标准
没有特殊要求的，统一采用 JSON 数据格式。
返回状态码
| 状态码 | 含义 | 说明 |
|---|---|---|
| 200（ok） | 服务器成功返回用户请求的数据，表明该操作是幂等操作 | 获取资源成功时返回此状态码，通常用于 GET 请求 |
| 201(CREATED) | 用户新建或修改数据成功，表明该操作非幂等操作 | 当用户提交数据尝试新建、修改数据记录成功时返回此状态码，通常用于 POST/PUT 请求 |
| 204(NOT CONTENT) | 用户删除操作成功 | 删除资源成功时返回此状态码，通常用于 DELETE 请求 |
| 400(INVALID REQUEST) | 请求错误，应用服务未进行新建或修改数据的操作 | 当用户提交数据尝试新建、修改数据记录时，应用服务对数据有效性校验发现数据不符合业务要求时，通常会返回此状态码 |
| 401(UNAUTHORIZED) | 表明用户没有有效身份信息 | 当用户会话令牌失效，服务器无法获得用户认证令牌时，返回此状态码 |
| 403(Forbidden) | 表明用户尝试访问被禁止获取的数据记录 | 当用户尝试打开一个并未授权其可以打开的文件时，应用服务返回此状态码 |
| 404(NOT FOUND) | 用户发出的请求针对的是不存在的记录，服务器没有进行操作 | 可能存在的情况：1. 服务器异常；2. 两个用户同时分别进行 DELETE 和 GET 操作，DELETE 操作先于 GET 执行 |
| 406(NOT Acceptable) | 用户请求的数据格式不符要求 | 通常是在 GET 请求时，尝试获取资源，但由于数据格式不符要求，导致获取资源失败 |
| 500(INTERNAL SERVER ERROR) | 应用服务发生错误 | 应用服务发生错误，不能正确接收服务请求 |
数据交换参考
获取列表数据
请求
GET /products?page=0&size=15&title=pad
成功的响应
状态码：200
响应内容：application/json
{
"content": [
{
"id": "1",
"title": "电脑pad",
"price": "5000"
},
{
"id": "2",
"title": "平板pad",
"price": "3000"
}
],
"number": 0, // 当前页
"size": 15, // 每页显示数
"totalPages": 1, // 总页数
"totalElements": 5 // 数据总数
}
失败响应
使用状态码表示失败响应
- 404 - 找不到资源
- 500 - 应用服务发生错误
新建数据
请求
POST /products
传参：
{
"title": "手机",
"price": "5000"
}
成功的响应
状态码：201、200
响应内容：application/json
{
"id": "100",
"title": "手机",
"price": "5000"
}
失败响应
使用状态码表示失败响应
- 500 - 应用服务发生错误
通过 id 获取一条数据
请求
GET /products/1
成功的响应
状态码：200
响应内容：application/json
{
"id": "1",
"title": "电脑",
"price": "5000"
}
失败响应
使用状态码表示失败响应
- 404 - 找不到资源
- 500 - 应用服务发生错误
更新一条数据
请求
PUT /products/1
传参：
{
"id": "1",
"title": "电脑",
"price": "10000"
}
成功的响应
状态码：201、200
响应内容：application/json
{
"id": "1",
"title": "电脑",
"price": "10000"
}
失败响应
使用状态码表示失败响应
- 404 - 找不到资源
- 500 - 应用服务发生错误
删除数据
请求
DELETE /products/1
成功的响应
状态码：200、204
响应内容：无
失败响应
使用状态码表示失败响应
- 404 - 找不到资源
- 500 - 应用服务发生错误