【笔记】对接接口定义标准化规范

[笔记系列文章说明]: 该类型的文章是笔者学习过程中整理的学习笔记.

与不绝对信任的机构或企业交换数据的时候, 通常需要考虑严格的数据安全问题, 我在这里定义了一种, 完整版就不放了, 列一些关键的点

文档定义

一, 接口访问定义

请求方式: http请求post方式
请求类型: application/json;charset=utf-8
返回类型: application/json;charset=utf-8
域名:

二, 参数定义

1. 请求头信息(Header)

参数	类型	说明	例
plantformCode	String	商家授权码	如:
timeStamp	Long	时间戳	如:1626255054672 (相当于2021-07-14 17:30:54)
sign	String	签名	8d2472fac5a4a1879bde18075f7a879e

2. 请求体内容(Body),具体内容依据具体接口

参数	类型	说明	例
messageId	String	消息唯一标识
data	String	JSON字符串
timeStamp	Long	时间戳
dataSource	String	数据来源,供应商唯一标识	如BOLIAN

{
"messageId":”9527”,
"data":"[{\"id\":54,\"gpsId\":\"Auth\",\"longitude\":18.98,\"latitude\":43.44,\"direction\":180,\"speed\":555,\"timeStamp\":1626321005219}]",
"timeStamp":1626321005219
}

3. 签名生成方式: MD5,32位,小写

• 第一步: 获取data内容
  例如:

String data = "{\"id\":54,\"gpsId\":\"Auth\",\"longitude\":18.98,\"latitude\":43.44,\"direction\":180,\"speed\":555,\"timeStamp\":1626321005219}";

• 第二步: append秘钥 (对接时由企橙提供唯一秘钥salt)

StringBuffer str = new StringBuffer(data).append(salt);

• 第三步: 进行MD5加密

sign=MD5(str)

4. 返回结果格式

参数	类型	说明	例
code	Integer	状态码	200:成功
message	String	消息内容
result	Json	接口返回内容
timeStamp	Long	时间戳

{
"code":stc200,
"message":stc"成功",
"result":stc{
"id":stc"9527",
"dataSource":stcnull,
"gpsId":stc"Auth"
},
"timeStamp":stc1626332760670
}

三, 接口内容

1. 车辆GPS数据上报接口
   描述: 接收供应商上传的GPS数据
   地址: http://域名/openApi/gps/push
   参数

参数名称	参数类型	是否必传	描述
id	String	是	记录唯一标识
gpsId	String	是	Gps唯一标识(设备号)
longitude	Double	是	经度
latitude	Double	是	纬度
direction	Integer	是	方向
speed	Integer	是	速度
timeStamp	Long	是	时间戳
参数例子

{
"messageId":"9527",
"data": "[{\"id\":9527,\"gpsId\":\"Auth\",\"longitude\":18.98,\"latitude\":43.44,\"direction\":180,\"speed\":555,\"timeStamp\":1626321005219}]",
"timeStamp":1626320711603 
}

返回

返回名称	返回类型	是否必返	描述
code	Integer	是	返回码,200:成功
message	String	是	返回消息
result	Json	否	返回内容
timeStamp	Long	是	时间戳
返回例子

{
"code": 200,
"message": "成功",
"result": null,
"timestamp": 1626332760670
}