这里写目录标题
API简要描述
注明作者信息,API功能
协议
通信协议使用https
域名
API应该部署在专用域名
例如:https://api.demo.com
版本化你的API
版本号放在API的url中
例如:https://api.demo.com/v1
路径
表示API的具体网址,restful风格中通常网址标识资源,只能有名词,且与数据库表名一致,常用复数形式。当使用API提供医院的信息,还包括部门,医生的信息时,API路径设计如下:
- https://api.demo.com/v1/hospitals
- https://api.demo.com/v1/departments
- https://api.demo.com/v1/doctors
请求类型
使用http动词表示请求类型
对同一资源所做的 增/删/改/查 操作的API,路径通常一样,只有发起请求的类型不同
前端写请求拦截器时通常把参数名为params的处理为query类型,把参数名为data的处理为body类型
如下:
常用类型
GET
常用于向服务器请求获取数据,可获取单条或列表
单条数据查询
请求参数通常拼接在URL后,即参数类型为query,如下:
https://api.demo.com/v1/doctors?id=2
请求列表
- API中通常需要加上list
- 常使用分页查询模式(传参pageIndex,pageSize)
- 可加入额外参数进行条件查询
- 参数类型为query
分页查询医生列表的API 可设计如下:
https://api.demo.com/v1/doctors/list?pageIndex=1&pageSize=10
POST
常用于向服务器请求新建资源,即对数据库进行插入操作的API
单条数据插入
请求参数通常放在请求体body里,参数类型为body,新增一个医生数据的API路径如下:
https://api.demo.com/v1/doctors
批量数据插入
- 路径通常需要加入batch
- 参数通常为数组
- 参数类型通常为body
批量增加医生数据的API路径如下:
https://api.demo.com/v1/doctors/batch
PUT
常用于向服务器请求修改资源,即对数据库进行修改操作的API
请求参数通常放在body里,例如修改一个医生信息的API路径如下:
https://api.demo.com/v1/doctors
DELETE
常用于向服务器请求删除资源,即对数据库进行删除数据操作的API
单条数据删除
参数通常拼接在url里,参数类型为query,删除一个医生信息的API路径如下:
https://api.demo.com/v1/doctors
批量删除
- 参数通常放在body里
- 参数通常为数组
- 路径通常要加batch
批量删除医生的API路径如下:
https://api.demo.com/v1/doctors/batch
不常用
PATCH
状态码
常用状态码如下:
- 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
- 202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
- 204 NO CONTENT - [DELETE]:用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
- 401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
- 403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
- 406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
- 410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
用于修改部分信息,参数为只需要修改的字段内容,而put需要提供该数据所有字段信息
错误处理
后台进行错误拦截后输入错误提示信息用于前台展示给用户
请求参数规范
将请求参数按参数名,类型,参数说明的表格形式展示,如下:
参数名称 | 类型 | 参数说明 | 是否必须 |
---|---|---|---|
pageIndex | number | 页码,默认为1 | false |
pageSize | number | 页大小,默认为10 | false |
返回结构与参数说明
返回结构通常固定为以下内容:
{
code: 200,
message: 'success',
data: {} / []
}
参数名 | 类型 | 说明 |
---|---|---|
id | bigint | id |
name | string | 名称 |
isRequired | int | 是否必填,1代表是,0代表否,默认1 |
type | string | 类型 |
RESTFUL接口文档示例
简要描述
- 作者:XXX
- 分页查询用户信息接口
请求URL
/demo/user/list
请求方式
- GET
参数类型
- QUERY
参数
参数名称 | 类型 | 参数说明 | 是否必须 |
---|---|---|---|
pageIndex | number | 页码,默认为1 | false |
pageSize | number | 页大小,默认为10 | false |
返回示例
{
"code": 200,
"message": "success",
"data": [
{
"id": "用户id",
"name": "用户名",
"nickName": "昵称",
"role": "角色",
"status": "状态",
},
{
"id": "用户id",
"name": "用户名",
"nickName": "昵称",
"role": "角色",
"status": "状态",
},
...
]
}
返回参数说明
参数名 | 类型 | 说明 |
---|---|---|
id | int | 用户id |
name | varchar | 用户名 |
nickName | varchar | 昵称 |
role | varchar | 角色 |
status | varchar | 状态 |
备注
- 根据筛选条件查询用户信息,若没有参数则返回全部用户信息