新版API接口文档

新版API接口文档

一、API接口请求规范

• 接口域名: https://api.jushuitan.com/

• 线上环境必须是https协议，苹果已声明必须使用https

• request、reponse的数据包： 使用json格式，字符集必须为utf-8

• 使用gzip方式请求，以便提高接口的传输效率

• 出入参数以驼峰规则，类似userName

入参协议示例：

{
    "name":"名字 [require | string | min:2 | max:8]",
    "age":"年龄 [require | int | min:1 | max:150]",
}

出参协议示例：

{
    "data":{
        "userName":"名字 [require | string | min:2 | max:8]",
        "age":"年龄 [int | min:1 | max:150]",
        "appVersion":"应用版本号 [string]",
        "img":[
            {
                "site":"图位号[require | int]",
                "file":"图片文件名.jpg[require]"
            }
        ]
    },
    "code":0,
    "act":0,
    "msg":"status message [string]"
}

二、API错误码规范

• 字端描述code：code对应一种特定的错误码

• 字端描述act：act对应一种特定的前端动作，act和code是一对多的关系；code=0 业务正确，code>0 业务错误，code<0 系统错误（会新增网关系统错误/服务端系统错误等）

• 字端描述msg：根据act来判断是否需要做msg显示

• act 动作码表

动作码表（act）	对应动作
0	正确，无动作（Web/App）
1	登出，需要重新登录（Web/App）
2	关闭app（App）
3	强制升级，升级文案为msg（App）
4	需要强提示用户，模态对话框，文案为msg，点击确定的时候关闭当前界面
5	需要弱提示用户，弹出toast，文案为msg

• code 系统错误码表

业务层状态码：大于0，分为以下两种,后续会扩展

finsh	code	act	描述	错误归属
❎	100001~200000	0	请求正确，业务错误	业务返回前台做特定处理
❎	1~100000	5	请求正确，业务错误	需要弹出toast
❎	0	0	成功
❎	-1	1	token失效	系统级错误码
❎	-2	2	危险用户	系统级错误码
❎	-3	3	客户端版本过低	系统级错误码
❎	-4	4	由于某些特殊原因被取消调用，通过接口弹出模态对话框，进行强制阻隔	系统级错误码
❎	-10000	5	此段开始定义网关api错误	系统级错误码，api错误码--------------------------------
❎	-10001	5	api 路经找不到	网关错误
❎	-10002	5	api 调用超时	网关错误
❎	-10003	5	api 时间偏差较大，风控风险，或者客户端需要时间校准	网关错误
❎	-10004	5	api header 格式出错，少必要字段	网关错误
❎	-10005	5	api header appkey 出错，风控风险	网关错误
❎	-10006	5	api header appsign 出错，风控风险	网关错误
❎	-10007	5	api request 格式错误，非json格式，新老接口通过版本区分	网关错误
❎	-10008	5	api request 缺少部分通用参数缺失	网关错误
❎	-10501	5	api管理相关，接口通过审核后未及时上线	api管理相关错误
❎	-10502	5	api管理相关，api服务未注册，如api未通过审核	api管理相关错误
❎	-10503	5	api管理相关，api方法未注册，如api未通过审核	api管理相关错误
❎	-10601	5	网关调用后台服务相关异常	后端服务调用异常预留）--------------------------------
❎	-11000	5	此段开始定义网关spi错误	spi错误码（预留）--------------------------------
❎	-12000	5	网关安全类错误	网关安全错误（预留）--------------------------------
❎	-12001	5	单位时间应用访问次数超出	网关安全错误
❎	-12002	5	单位时间api访问次数超出	网关安全错误
❎	-12003	5	单位时间token访问次数超出	网关安全错误
❎	-12004	5	单位时间设备访问次数超出	网关安全错误
❎	-20000	5	此段开始定义网关聚合类错误	网关聚合类接口错误码--------------------------------

三、前后端接口通信协议约定

通信采用https的post方式进行数据交互。通信协议中header必须包含以下内容：

请求头类型	请求头	定义	描述
通用	jst-pv: 1.0.0	网络通信协议版本号	起始值0.9.0
通用	jst-sdkv: 1.0.0	网络库SDK版本号	起始值0.9.0
通用	jst-appkey:ios_pda_global	大前端领域内端的标识	类型包含ios/android/flutter/mp/h5/web，pda、pda_global代表业务
通用	jst-ts: 1488445016324	请求时间戳	精度到ms
通用	jst-screen: 1080;1812;xxhdpi	设备屏幕的信息	格式：代表长,宽,精度
通用	jst-static: Android;5.0.2;phone;Xiaomi;Redmi Note 2	手机的部分静态信息	格式：手机类型、系统版本号、手机厂商、手机型号，后续可能会再扩展增加，对应字段获取不到时保留“;;”。适用于Android、iOS、Flutter、以及能获取这类静态数据的宿主环境。参考：IOS;10.2;phone;iphone;iPhone 6
通用	jst-ssotoken: 352bb25254499bba4dca64f85e29013d	登录态信息	当用户登录时，后端会将登录信息sso_token带入Cookie，此时客户端通过CookieMananger进行管理，前端按照Cookie方式进行管理。登录时做本地保存，用户登出时统一进行Cookie清除。
for app	jst-appv: 2.2.0	app版本号	对应app每个需求版本
for app	jst-appb: 96	app编译号	针对appv进行进一步的区分，用于网关/服务端做兼容处理，例如2.2.0可能会有91、92两个版本
for app	jst-channel: appstore	app的渠道来源	iOS：appstore；Android：yingyongbao 应用宝市场、360 360市场、baidu 百度市场、wandoujia 豌豆荚市场、xiaomi 小米市场、meizu 魅族市场、 huawei 华为市场、 chuizi 锤子市场 、 oppo oppo市场 、 vivo vivo市场 、jst 升级或者刷二维码的android用户
for app	jst-devid: 861759037761110	设备唯一识别号	需要保证唯一，app卸载重装不能变，ios/android/flutter各端需要传
for app	jst-n: wifi	当前网络类型	网络类型 2g、3g、4g、5g、wifi，有网络切换需要进行切换监听
for app	jst-location: 120.111394;30.269177	定位信息	业务层面有使用定位信息，那定位成功后必须传递，格式"经度,维度"，保留6位小数可以达到约1米精度。
for app	jst-sign: gde89898wq98ewhjkjn2kj282	加签信息	用于防止中间人攻击

签名的生成算法(Signature)

此为基本安全验证机制，必须使用，签名不正确服务端将拒绝请求访问。各端都需要有一个secret，iOS、Android、H5都不同，防止各端同时被破解，android需要写到so里面

接口签名规则：

• 所有 “jst-” 开头的自定义请求头都参与加签，按照首字母进行ASCII码顺序排列
• 再将请求所有业务参数按照首字母进行ASCII码顺序排列
• 拼接字符串,密钥＋jst-开头的所有请求头参数+ resquest body，例如：sgin=sha1(secret=1755c118e8859eb0&jst-appb=95&jst-appkey=fitness&jst-appv=2.4.1&jst-channel=jst&jst-devid=861365031971224&jst-pv=1.0&jst-screen=1080,1920,px&jst-sdkv=1.0.0&jst-timestamp=1496211400424&data={“cityId”:12974})
• 将签名后的值，传入请求头jst-sign