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	设备回复超时

iThings API 定义方式

iThings API 定义方式#

目录#

1 规范#

1.1 Header头信息#

1.2 Request请求#

1.3 Response响应#

1.4 Misc其他#

2 路径前缀#

2.1 数据图表#

2.2 系统管理#

3 返回码表#

3.1 返回格式#

3.2 HTTP默认返回#

3.3 公共错误码#

3.4 用户错误码#

3.5 设备错误码#

iThings API 定义方式

目录

1 规范

1.1 Header头信息

1.2 Request请求

1.3 Response响应

1.4 Misc其他

2 路径前缀

2.1 数据图表

2.2 系统管理

3 返回码表

3.1 返回格式

3.2 HTTP默认返回

3.3 公共错误码

3.4 用户错误码

3.5 设备错误码