API交互规范

API 规则

• API 遵循RESTful设计风格 RESTful API 设计指南 (opens new window)
• 混合开发中，在Native 嵌 H5 时，访问API的协议需一致（https 或 http）
• 生产环境使用 https:// 协议

请求响应规则

HTTP请求或响应体的内容类型

数据类型 Content-Type 为 application/json

流媒体类型 image/*、audio/*、video/*

请求基础参数 Header

X-MMM-DeviceType:     // 设备类型 如. 0=ios、1=android
X-MMM-Version:        // 版本号
X-MMM-Timestamp:      // 时间戳
X-MMM-Uuid:           // UUID
X-MMM-Sign:           // 加密签名
X-MMM-AccessToken:    // 访问Token

请求与响应JSON格式

// 客户端请求参数
{
    "pageSize": 20,
    "pageNumber": 0
}

// 服务端响应JSON
{
    "code": 0,              // 状态码，0成功
    "msg" : "获取信息成功",   // 提示文本信息
    "data": {               // 业务数据
        "list": [
            [
                "悲伤",
                "喜悦",
                "平淡"
            ],
            [
                "职场",
                "生活",
                "校园"
            ]
        ]
    }
}

客户端基础模型

// 客户端模型解析
data class ResponseBase {
    /**
     * 响应码（0成功）
     */
    var code: Long
    
    /**
     * 响应提示信息
     */
    var msg: String
    
    /**
     * 响应数据JSON字符串（转换成具体对象模型）
     */
    var data: String
}

响应模型

一致性

• API在返回数据结构时，同性质对象模型，属性命名必须一致

错误案例：

// 接口A /commpanys
{              
    "company": {
        "companyId": 100256,   
        "companyName": "天联共创",   
    }
}


// 接口B /commpany/detail
{              
    "companyDetail": {
        "cId": 100256,   
        "cName": "天联共创",   
    }
}

Token授权

Token登录授权流程示意图

授权流程

• 账号密码/手机验证码 进行登录后获取 authCode
• authCode 获取 accessToken、refreshToken
• accessToken 访问API
• accessToken 访问API过期，通过refreshToken，重新刷新accessToken的有效期