接口定义规范
| 版本 | 更新日志 | 备注 |
|---|---|---|
| 1.0.0 | 2019-01 | 接口定义规范首版本 |
| 1.1.0 | 2019-12 | 接口定义规范更新1.1.0 |
一、版本控制
https://gateway.eazytec-cloud.com/{app_name}/v{n}/{module}
- 应该将API的版本号放入URL。
- app_name代表项目的名称。
- module代表具体的业务模块，如用户模块，产品模块。
- 采用多版本并存，增量发布的方式。
- n代表版本号，分为整型和浮点型
- 整型： 大功能版本， 如v1、v2、v3 ...
- 浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...
- 对于一个 API 或服务，应在生产中最多保留 3 个最详细的版本
- URL请求中不采用大小写混合的驼峰命名方式，尽量采用全小写单词，如果需要连接多个单词，则采用连接符“_”连接单词
二、请求方式
2.1 HTTP动词
- GET（SELECT） 从服务器取出资源（一项或多项）
- POST（CREATE） 在服务器新建一个资源
- PUT（UPDATE） 在服务器更新资源（客户端提供改变后的完整资源）
- PATCH（UPDATE） 在服务器更新资源（客户端提供改变的属性）
- DELETE（DELETE） 从服务器删除资源
2.2 举例
- GET /zoos 列出所有动物园
- POST /zoos 新建一个动物园
- GET /zoos/{id} 获取某个指定动物园的信息
- PUT /zoos/{id} 更新某个指定动物园的信息（提供该动物园的全部信息）
- PATCH /zoos/{id} 更新某个指定动物园的信息（提供该动物园的部分信息）
- DELETE /zoos/{id} 删除某个动物园
- GET /zoos/{id}/animals 列出某个指定动物园的所有动物
- DELETE /zoos/{id}/animals/{id} 删除某个指定动物园的指定动物
2.3 注意
- 要防止出现如下这种的路径冲突
- GET /people/{deptid} 列出某个部门的所有人员
- GET /people/{categoryid} 列出某个类别的所有人员
- 应该改为如下的这种形式
- GET /dept/{deptid}/people 列出某个部门的所有人员
- GET /category/{categoryid}/people 列出某个类别的所有人员
2.4 GET与POST对比
| GET | POST | |
|---|---|---|
| 后退按钮/刷新 | 无害 | 数据会被重新提交（浏览器应该告知用户数据会被重新提交） |
| 书签 | 可收藏为书签 | 不可收藏为书签 |
| 缓存 | 能被缓存 | 不能缓存 |
| 编码类型 | application/x-www-form-urlencoded | application/x-www-form-urlencoded或multipart/form-data，为二进制数据使用多重编码 |
| 历史 | 参数保留在浏览器历史中 | 参数不会保存在浏览器历史中 |
| 对数据长度的限制 | 是的，当发送数据时，GET方法向URL添加数据；URL的长度是受限制的（URL的最大长度是2048个字符） | 无限制 |
| 对数据类型的限制 | 只允许ASCII字符 | 没有限制，也允许二进制数据 |
| 安全性 | 与POST相比，GET的安全性较差，因为所发送的数据是URL的一部分。在发送密码或其他敏感信息时绝不要使用GET | POST比GET更安全，因为参数不会被保存在浏览器历史或web服务器日志中 |
| 可见性 | 数据在URL中对所有人都是可见的 | 数据不会显示在URL中 |
2.5返回结果
- GET /collection 返回资源对象的列表（数组）
- GET /collection/resource 返回单个资源对象
- POST /collection 返回新生成的资源对象
- PUT /collection/resource 返回完整的资源对象
- PATCH /collection/resource 返回完整的资源对象
- DELETE /collection/resource 返回一个空文档
2.6 过滤信息
- ?limit=10 指定返回记录的数量
- ?offset=10 指定返回记录的开始位置
- ?page_num=2&page_size=100 指定第几页，以及每页的记录数
- ?sortby=name&order=asc 指定返回结果按照哪个属性排序，以及排序顺序
- ?animal_type_id=1 指定筛选条件