api接口设计规范

  1. 前言
    本规范旨在为公司各业务系统之间业务复用及整合的API提供接口调用与交互规范。同时,也作为未来公司业务系统内各应用模块之间以及各业务系统之间,基于面向服务的架构,以服务接口的方式,提供数据和各种功能的一种尝试。
    1.1 术语和定义
    缩写 全称 说明

1.2 适用对象
本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的API,统一采用UTF-8编码规则,采用JSON格式响应。
2. 数据包格式规范
2.1 URL定义
API 服务接口应提供REST风格的HTTP(HTTPS) 接口:
{protocol}/{domain}:{port}/{type}/{function}/{action}?{query}
变量 含义 示例
protocol 接口协议 HTTP、HTTPS
domain 网关ip地址或者网关域名 api.xxx.com
port 网关端口号 80、8080
Type 功能类别 SMSManage、UserManage等
function 功能名称 UserInfo、DepartmentInfo
action 操作类别(可空) CREATE、SELECT、UPDATE、DELETE等
query由系统级参数部分和具体API调用参数部分组成,以key1=value1&key2=value2&…表示。
对于采用POST请求的Open API,query部分则是在POST请求体里。
2.2 请求头格式
名称 必填 描述
Content-Type 是 application/x-www-form-urlencoded;charset=utf-8;
或application/json;charset=utf-8;
2.3 系统级请求参数
名称 必填 描述
appid 是 请求账号
timestamp 是 Unix时间戳,即从1970年1月1日0时0分0秒开始所经过的秒数(安全验证有效期60秒,防replay攻击)
sign_type 否 安全验证方式,默认为MD5。
sign 是 加密字符。
2.4 应用级请求参数
名称 类型 描述
pageindex Int 分页索引,默认为1
pagesize Int 分页量,表示每一页返回多少条数据,默认10,上限50
2.5 参数签名算法
系统提供MD5加密方式调用,默认为加密方式sign_type为MD5。MD5的加密步骤为:
步骤一:构造加密前的字符串
调用方将除“sign”以外的GET请求参数按照参数名称(Key),进行字典升序排序,并将Api接口地址(apiname)和排序后的参数用&拼接起来,参数的值需使用URL编码。
例如:/user/info/select?appid=123456×tamp=1361461671。
步骤二:生成加密字符
使用MD5将步骤一生成的字符串+“&secret=秘钥”加密,并将加密后的字符串转换为小写。
执行完上述步骤,即可获取加密字符串,作为sign的值。
3. 接口请求示例
3.1 完整请求示例()

  1. 服务端接口验证示例
    4.1 安全验证步骤
    通过请求的参数,多步验证。
    ◆ 验证请求参数是否完整。
    ◆ 验证时间戳是否有效(安全验证有效期60秒)。
    ◆ 根据业务需求添加是否验证请求频次。
    ◆ 根据业务需求验证时间戳是否已经请求过。
    ◆ 根据业务需求验证IP限制、时间限制等。
    ◆ 验证加密字符串。
    4.2 安全验证示例()
    建议将安全验证应用在MVC的过滤器里。
  2. 服务端响应格式
    5.1 响应输出格式
    服务端正常输入应该符合如下的JSON格式:
    ◆ http响应头中的Content-Type指定为application/json, charset=utf-8
    ◆ 字符串编码格式是UTF-8。
    ◆ 输出格式为:
    {
    “code”: “响应码(数值型)”:,
    “message”: “响应描述(字符串)”,
    “data”:"[response body](JSON字符串)"
    }

[response body]可为空。
5.2 响应输出示例
API接口请求成功时候响应示例:
{
“code”: 200,
“message”: “请求成功”,
“data”: null
}
API接口请求失败时候响应示例:
{
“code”: 402,
“message”: “请求已过期”,
“data”: null
}
5.3 响应状态码类别
名称 类型 描述
200 Int 请求成功
100 Int 1** 表示请求的参数错误等问题
300 Int 3** 表示业务逻辑等问题
400 Int 4** 表示安全验证等问题
500 Int 5** 表示内部错误等问题
5.4 响应状态码字典
名称 描述
200 请求成功

400 安全验证未通过
401 请求账号为空
402 加密字符为空
403 请求已过期

你可能感兴趣的:(后端,json,http)