文档中心 > 开放平台

API调用说明

开放平台(PSDM)的API是基于HTTP协议来调用的,开发者(ISV)可以直接使用TOP提供的官方SDK(支持多种语言,包含了请求的封装,签名加密,响应解释,性能优化等)来调用,也可以根据PSDM的协议来封装HTTP请求进行调用,以下主要是针对自行封装HTTP请求进行API调用的原理进行详细解说。

调用流程

根据PSDM的协议:填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json结果,以下是大体的调用过程示意图:

image

公共参数

请求地址:

环境HTTP请求地址HTTPS请求地址
正式环境暂不支持https://api.smallec.com/router/rest
测试环境http://apitest.smallec.com/router/rest暂不支持

公共请求参数:

名称类型是否必须描述
methodStringAPI接口名称。
app_keyString应用的AppKey。
sessionString用户登录授权成功后,PSDM颁发给应用的授权信息,详细介绍请点击这里。当此API的标签上注明:“需要授权”,则此参数必传;“不需要授权”,则此参数不需要传;“可选授权”,则此参数为可选。
timestampString时间戳,格式为yyyy-MM-dd HH:mm:ss,时区为GMT+8,例如:2015-01-01 12:00:00。API服务端允许客户端请求最大时间误差为10分钟。
vStringAPI协议版本,可选值:1.0。
sign_methodString签名的摘要算法,可选值:md5。
signStringAPI输入参数签名结果,签名算法参照下面的介绍。

业务参数

API调用除了必须包含公共参数外,如果API本身有业务级的参数也必须传入,每个API的业务级参数请考API文档说明。

签名算法

为了防止API调用过程中被黑客恶意篡改,调用任何一个API都需要携带签名,TOP服务端会根据请求参数,对签名进行验证,签名不合法的请求将会被拒绝。TOP目前支持的签名算法有两种:MD5(sign_method=md5),HMAC_MD5(sign_method=hmac),签名大体过程如下:

  • 对所有API请求参数(包括公共参数和业务参数,但除去sign参数和byte[]类型的参数),根据参数名称的ASCII码表的顺序排序。如:foo=1, bar=2, foo_bar=3, foobar=4排序后的顺序是bar=2, foo=1, foo_bar=3, foobar=4。

  • 将排序好的参数名和参数值拼装在一起,根据上面的示例得到的结果为:bar2foo1foo_bar3foobar4。

  • 把拼装好的字符串采用utf-8编码,使用签名算法对编码后的字节流进行摘要。如果使用MD5算法,则需要在拼装的字符串前后加上app的secret后,再进行摘要,如:md5(secret+bar2foo1foo_bar3foobar4+secret);如果使用HMAC_MD5算法,则需要用app的secret初始化摘要算法后,再进行摘要,如:hmac_md5(bar2foo1foo_bar3foobar4)。

  • 将摘要得到的字节流结果使用十六进制表示,如:hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F726C64”

说明:MD5和HMAC_MD5都是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32个十六进制字符。

调用示例

psdm.time.get调用为例,具体步骤如下:

1. 设置参数值

公共参数:

method = “psdm.time.get”
app_key = “12345678”
session = “test”
timestamp = “2016-01-01 12:00:00”
format = “json”
v = “1.0”
sign_method = “md5”

业务参数:


2. 按ASCII顺序排序

app_key = “12345678”
format = “json”
method = “psdm.time.get”
session = “test”
sign_method = “md5”
timestamp = “2016-01-01 12:00:00”
v = “1.0”

3. 拼接参数名与参数值

app_key12345678formatjsonmethodpsdm.time.getsessiontestsign_methodmd5timestamp2016-01-01 12:00:00v1.0

4. 生成签名

假设app的secret为helloworld,则签名结果为:hex(md5(helloworld+按顺序拼接好的参数名与参数值+helloworld))="AEF9405FE8524E3844075EB573EFD762"

5. 组装HTTP请求
将所有参数名和参数值采用utf-8进行URL编码(参数顺序可随意,但必须要包括签名参数),然后通过GET或POST(含byte[]类型参数)发起请求,如:

http://api.smallec.com/router/rest?method=psdm.time.get&v=1.0&sign_method=md5&app_key=10003&format=json&timestamp=2016-01-01+12%3a00%3a00&sign=AEF9405FE8524E3844075EB573EFD762

注意事项

  1. 所有的请求和响应数据编码皆为utf-8格式,URL里的所有参数名和参数值请做URL编码。如果请求的Content-Type是application/x-www-form-urlencoded,则HTTP Body体里的所有参数值也做URL编码;如果是multipart/form-data格式,每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8。

  2. 参数名与参数值拼装起来的URL长度小于1024个字符时,可以用GET发起请求;参数类型含byte[]类型或拼装好的请求URL过长时,必须用POST发起请求。所有API都可以用POST发起请求。

  3. 如需需要在沙箱环境测试,请在应用控制台的沙箱管理页面获取沙箱环境对应的app_key(一般为正式环境的app_key前面加上“10”)和app_secret,对应的session值也用沙箱帐号登录授权获得,沙箱环境授权和正式环境授权类似,详细可参考用户授权介绍

  4. 生成签名(sign)仅对未使用TOP官方SDK进行API调用时需要操作,如使用了TOP官方SDK,该步骤SDK会自动完成。