API文档约定
# API文档约定
提示
🚀阅读API开发文档前,请先阅读本文档。 本文档说明了API调用的规则和请求URL以及通用数据格式。
注意
现在还是测试阶段,如果请求接口报错,及时反馈给我,我会24h内处理。
另外:SDK正在开发过程中,敬请期待,如果你想封装SDK请联系我。
# 请求URL
# 认证规则
所有请求都需要应用的认证信息,通过app_key
和app_sign
两个头部信息进行认证。请所有请求信息中放入这两个Http Header
信息。
app_key
是应用的key信息,在管理后台创建应用后在应用信息面板可以查看.app_sign
是根据应用的app_secret
信息MD5得到,在管理后台创建应用后在应用信息面板可以查看应用的secret.
# 请求URL
API接口文档中只说明了请求路径,没有说明请求URL,所有接口的请求URL为:
https://api.dottools.top/api
如果不想使用https可以使用http接口为:
http://api.dottools.top/api
# 通用数据格式
# 返回数据格式
返回数据的统一格式为:
{
"code": 0,
"msg": "success",
"data": {...}
}
//或者
{
"code": 0,
"msg": "success",
"data": [...]
}
# 返回参数解释
- 当code为0时,表示请求成功。data中时返回成功的对象,如果是删除等操作,data为null
- 当code不为0时,表示请求失败。msg中是失败的原因。
# API文档格式说明
# 🌰例子
下面以一个请求文档为例子讲解API文档格式:
请求路径 /app/datatable/{table_name}
请求协议 HTTP
请求方法 POST
请求头部:
头部标签 | 必填 | 说明 | 类型 | 限制 | 头部内容 |
---|---|---|---|---|---|
app_key | 是 | app_key | |||
app_sign | 是 | 参见认证规则 |
请求参数 Json Object
参数名 | 说明 | 必填 | 类型 | 值可能性 | 限制 | 示例 |
---|---|---|---|---|---|---|
key | 存储数据唯一标示,只能包含数字、字母、下划线 | 是 | string | |||
data | 这里面放入你自己定义的json数据即可,定义json数据根部不能有key字段,key字段会被自动忽略 | 是 | object |
REST参数:
参数名 | 说明 | 必填 | 类型 | 值可能性 | 限制 | 示例 |
---|---|---|---|---|---|---|
table_name | 数据表的名字,只能包含数字、字母、下划线 | 是 | string |
# 说明
API文档的格式主要包括以下几个部分:
- 请求路径
该API的请求路径,请求URL (opens new window)加上该请求路径为完整请求路径。如果路径中有大括号扩起来的路径,表示了该部分为REST参数,例如/app/datatable/{table_name}
中{table_name}
为REST参数,需要你自己去传入。 - 请求协议
目前都是HTTP协议。 - 请求方法
HTTP协议的请求方法,包括常用的GET, POST, PUT, DELETE
。 一般来讲:GET
表示查询获取数据,POST
表示新增数据或者进行一些逻辑操作,PUT
表示更新数据,DELETE
表示删除数据。 - 请求头部
HTTP请求头部,将该参数放入HTTP Header
中。 - 请求参数
请求的参数,常见有Query参数、表单参数、Json参数
GET
请求中只有Query参数,POST/PUT
请求中三种参数都有- Query参数:是拼接到路径中的参数,比如路径为
/app/datatable/{table_name}
的请求,有多个pageSize
和pageNum
的Query参数,在Http中就会拼接到路径后,/app/datatable/{table_name}?pageSize=10&pageNum=1
- 表单参数:表示有Http请求体的网络请求,会将参数以Form表单形式放在Http请求体中,以
username
和email
的表单参数为例子,就会在请求体中发送内容为:username=XXX&email=XXX
- Json参数:表示有Http请求体的网络请求,会将参数以Json形式放在Http请求体中,以
username
和email
的Json Object参数为例子,就会在请求体中发送内容为:
{ "username": "XXX", "email": "XXX" }
- Query参数:是拼接到路径中的参数,比如路径为
- REST参数
该参数为请求路径中的参数,在请求路径中使用大括号表示。例如/app/datatable/{table_name}
中{table_name}
为REST参数,需要你自己去传入。