iThings API 定义方式
iThings API 定义方式
目录
1 规范
1.1 Header头信息
- 通过header传递app_id/app_key/token等信息
- 通过 body 传递变量和参数
1.2 Request请求
- 通过 json 方式传递请求的变量和参数
- 标准CRUD方法通过 create/read/update/delete/softdelete/index 等方式进行操作
- 所有请求的 method 都使用 POST 方法
- 请求响应可携带 guid 用于定位每次接口调用的日志
- 拼接路径的时候,如果需要连接单词,则使用减号,例如:
/api/v1/hello-world
- 在需要申请时间相关的数据的时候,若获取一日数据,则默认取当天日期;若取时间跨度数据,默认为从昨天到今天的数据。
1.3 Response响应
- 通过 json 方式返回 api 调用结果
- 所有返回信息都使用 { code, msg, data } 的数据结构,所有属性可以传递空置,但是不可以省略
- 返回的数据结构中对象名称如果使用{$x}方式标记的,表明可以用字符串替换,非固定定义的名称
1.4 Misc其他
- 前缀:使用
/api/v1
作为所有api的公用前缀 - 格式:
/api/v1/{一级分组}/{二级分组}/../{域模型}/{方法}
2 路径前缀
2.1 数据图表
路径前缀:/api/v1/charts
- 柱状图
2.2 系统管理
路径前缀:/api/v1/system
-日志管理
路径前缀:/api/v1/system/log
- 应用管理
路径前缀:/api/v1/system/app
- 用户权限管理
路径前缀:/api/v1/system/auth
3 返回码表
3.1 返回格式
返回格式(json):
{
"code": <integer>,
"msg": <string>,
"data": <object>
}
例子:
- 正确: 200状态码,直接返回对应的数据如下:
{ "code": 200, "msg": "success", "data": { "uid": "1734383442971357184", "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVaWQiOjE3MzQzODM0NDI5NzEzNTcxODQsImV4cCI6MTY1NTY0ODMwNiwiaWF0IjoxNjU1NjQ3NzA2fQ.SPuZQJPyfOwshHcOY1Ypn_8jI5-jsTVrAnUjj0_PMgk", "accessExpire": "1655648306" } }
- 错误: 400状态码,返回错误信息结构如下:
{ "code": 1000005, "msg": "验证码错误", "data": "" }
- 权限未通过: 401状态码,返回错误信息如下结构:
{ "code": 100002, "msg": "token已经过期", "data": "" }
3.2 HTTP默认返回
英文定义 | 错误码 | 说明 |
---|---|---|
OK | 200 | 服务器成功返回请求的数据。 |
Created | 201 | 新建或修改数据成功 |
Accepted | 202 | 一个请求已经进入后台排队(异步任务) |
NoContent | 204 | 请求成功,但无返回内容 |
BadRequest | 400 | 发出的请求有错误,服务器没有进行新建或修改数据的操作。 |
Unauthorized | 401 | 用户没有权限(令牌、用户名、密码错误)。 |
Forbidden | 403 | 用户得到授权,但是访问是被禁止的。 |
NotFound | 404 | 发出的请求针对的是不存在的记录,服务器没有进行操作 |
NotAcceptable | 406 | 请求的格式不可得 |
Gone | 410 | 请求的资源被永久删除,且不会再得到的。 |
UnprocessableEntity | 422 | 当创建一个对象时,发生一个验证错误。 |
InternalServerError | 500 | 服务器发生错误,请检查服务器 |
BadGateway | 502 | 服务器发生错误,请检查服务器。 |
ServiceUnavailable | 503 | 服务不可用,服务器暂时过载或维护。 |
GatewayTimeout | 504 | 网关超时。 |
3.3 公共错误码
英文定义 | 错误码 | 说明 |
---|---|---|
Default | 100001 | 其他错误 |
TokenExpired | 100002 | token已经过期 |
TokenNotValidYet | 100003 | token还未生效 |
TokenMalformed | 100004 | token格式错误 |
TokenInvalid | 100005 | 违法的token |
ParameterError | 100006 | 参数错误 |
SystemError | 100007 | 系统错误 |
DatabaseError | 100008 | 数据库错误 |
NotFound | 100009 | 未查询到 |
Duplicated | 100010 | 参数重复 |
SignatureExpired | 100011 | 签名已经过期 |
PermissionError | 100012 | 权限不足 |
MethodError | 100013 | method不支持 |
TypeError | 100014 | 参数的类型不对 |
OutRanged | 100015 | 参数的值超出范围 |
TimeOut | 100016 | 等待超时 |
Fault | 100017 | 本实例处理不了该信息 |
NotRealized | 100018 | 尚未实现 |
3.4 用户错误码
英文定义 | 错误码 | 说明 |
---|---|---|
UserDuplicated | 1000001 | 用户名已经注册 |
MobileDuplicated | 1000002 | 手机号已经被占用 |
UnRegistered | 1000003 | 未注册 |
AccountOrPasswordError | 1000004 | 账号或密码错误 |
CaptchaError | 1000005 | 验证码错误 |
UidFailed | 1000006 | uid不对 |
RegisterStepOneError | 1000022 | 注册第一步未成功 |
RegistrationDuplicated | 1000023 | 重复注册 |
UsernameRequired | 1000024 | 需要填入用户名 |
LackOfPasswordStrength | 1000025 | 密码强度不够 |
GetInfoPartFailure | 1000026 | 获取用户信息有失败 |
3.5 设备错误码
英文定义 | 错误码 | 说明 |
---|---|---|
ResponseParamError | 2000001 | 返回参数不对 |
DeviceTimeOut | 2000002 | 设备回复超时 |
修改时间 1 年前