开放平台说明
1.1用途
本接口规范面向技术人员,用于指导HTTP接口的设计、开发和规范使用,保护接口双方系统的安全。
1.2术语
1.2.1接口提供方(API Provider)
接口的定义和实现者,为接口调用方提供接口合法访问的授权。
1.2.2接口调用方(API Client)
接口的调用者,需要从接口提供方获得所需接口合法访问的授权。
1.2.3接口端点(API Endpoint)
是接口的Http资源入口,由一个Http URL所表示,代表了一个或由参数确定的多个接口的集合。
1.3规范定义
1.3.1接口调用方式
GET---向接口端点请求由请求参数所代表的资源,为等幂调用,通常响应结果可缓存(应根据响应头决定)。
POST---向接口端点发送由请求参数所代表的资源,是否等幂取决于接口的语义,通常响应结果不可缓存(应根据响应头决定)。
1.3.2接口格式
GET格式为:GET <API Endpoint>{?|&}参数列表
POST格式为:POST <API Endpoint>
参数列表
参数列表格式为:参数名1=参数值1&参数名2=参数值2......,其中参数值均应使用URLEncode进行编码。
1.3.3接口响应
根据接口实现的功能和语义,接口有以下几种返回方式:
A.重定向---将Client重定向到指定的URI,在URI后添加输出参数。
B.响应体---将要返回给Client的结果放入请求的输出流中,结果通常为HTML(如:Content-Type=text/html)或者数据对象(如:Content-Type=application/json)。
C.异步回调---接口提供方通过异步方式向预先约定或通过参数指定的URI发送请求。
1.3.4统一请求地址
http://apipsp.yj.com.qa/api
1.3.5请求标准参数
参数名称 | 参数说明 |
---|---|
method | 由接口提供方指定的接口标识符。 |
sign_type | 由接口提供方指定的签名加密类型。 |
appid | 由接口提供方分配给接口调用方的身份标识符。 |
version | 由接口提供方指定的接口版本。注:Endpoint+ method+version决定了接口的语义。 |
timestamp | 调用方时间戳,格式为“4位年+2位月+2位日+2位小时(24小时制)+2位分+2位秒”,用于接口提供方判断调用方的时间,通常约定调用请求的时间戳与接口提供方收到请求的时间差在约定的范围内。 |
sign | 签名,按照签名生成算法计算得来。 |
data | 具体的接口方法中的参数实体信息(对象需要转换成JSON String) |
1.3.6统一返回参数结构
参数名称 | 参数说明 |
---|---|
Code | 处理结果编码(参考数据字典的“标准错误代码”) |
Message | 处理结果消息 |
Data | 接口处理完毕返回的数据(请参见具体接口的返回信息)。 |
例如
RequestBody(URLEncode前):
method=stockAdjust&sign_type=md5&version=1.0&appid=1×tamp=20141126133300&sign=23697537dc822216fdded329361f4311ea9f&data={"phone": ["12345678","87654321"],"name": "zhangsan","age": 100,"address": {"country": "china","province": "chengdu"},"married": false}
返回的Json格式:
{"Code":"0","Message":"",”Data”:{“SONO”:”100000”}