用户按照当当的规范拼装一个正确的URL,通过HTTP请求,就能够拿到用户自己需要的数据。
当当API (接口) 采用 REST 风格,只需将所需参数拼装成http请求,即可调用。故支持 http 协议请求的程序语言,均可调用当当API,例如php、C#、asp、java、delphi 等。
环境地址,即调用接口(API)时,都通过访问该地址,来获取该接口需要获取的数据
正式环境:https://gw-api.dangdang.com/openapi/rest?v=1.0
http://api.open.dangdang.com/openapi/rest?v=1.0 (已弃用)
调用API ,必须传入系统参数和应用参数。系统参数是调用每个api时默认的必填参数;应用参数由于不同 API 各自不同,这里以dangdang.item.itemid.get为例说明,更多请参考API文档。
1. 系统级调用参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
method |
string |
Y |
API接口名称 |
timestamp |
string |
Y |
时间戳,格式为yyyy-MM-dd HH:mm:ss,例如:2013-05-06 13:52:03 |
format |
string |
Y |
可选,指定响应格式。默认xml,目前支持格式为xml |
app_key |
string |
Y |
分配给应用的AppKey,创建应用时可获得 |
v |
string |
Y |
API协议版本,可选值:1.0 |
sign |
string |
Y |
对API输入参数进行md5加密获得,详细参考签名sign |
sign_method |
string |
Y |
参数的加密方法选择,可选值是:md5 |
session |
string |
Y |
分配给用户的SessionKey(或 Access Token),通过登陆授权获取,方法参考用户授权介绍。
API文档上“API用户授权类型”标识为“需要”的,调用时均要传该参数
|
2. 应用参数
此处以dangdang.item.itemid.get接口为例,查看其他接口的应用参数请参照对应页面。
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
oit |
string |
Y |
企业商品标识符 |
3. 签名sign
调用API时需要对请求参数进行签名验证,服务器也会对该请求参数进行验证是否合法的。方法如下:
(1)根据参数名称(除签名和图片)将所有系统级参数按照字母先后顺序排序:key + value .... key + value
例如:将method=dangdang.item.itemid.get,timestamp=2013-06-20 19:33:00,format=xml,app_key=21000000515,v=1.0,sign_method=md5,session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063排序为app_key=21000000515,format=xml,method=dangdang.item.itemid.get,session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063,sign_method=md5,timestamp=2013-06-20 19:33:00,v=1.0,参数名和参数值链接后,得到拼装字符串app_key2100000826formatxmlmethoddangdang.item.itemid.getsession4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063sign_methodmd5timestamp2013-06-20 19:33:00v1.0
(2)系统支持MD5加密方式
md5:将secret(App Secret)拼接到参数字符串头、尾(以上参数拼接后为5FDD35D3A94D73514CD6F1A5B58AED53app_key2100000826formatxmlmethoddangdang.item.itemid.getsession4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063sign_methodmd5timestamp2013-06-20 19:33:00v1.05FDD35D3A94D73514CD6F1A5B58AED53)进行md5加密后,再转化成大写,格式是:md5(secretkey1value1key2value2...secret)
注:我们需要的是32位的大写字符串
4. 调用实例
调用API:dangdang.item.itemid.get,使用系统默认MD5加密,因为各语言语法不一致,以下实例只体现逻辑。
(1)输入参数为:
method=dangdang.item.itemid.get
timestamp=2013-05-06 13:52:03
format=xml
app_key=2100000826
v=1.0
sign_method=md5
session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063
oit=123abcde
(2)系统级参数按照参数名称升序排列:
app_key=2100000826
format=xml
method=dangdang.item.itemid.get
session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063
sign_method=md5
timestamp=2013-05-06 13:52:03 (时间必须是当前+8区北京时间)
v=1.0
(3)连接字符串
连接参数名与参数值,并在首尾加上secret,如下:
5FDD35D3A94D73514CD6F1A5B58AED53app_key2100000826formatxmlmethoddangdang.item.itemid.getsession4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063sign_methodmd5timestamp2013-05-06 13:52:03v1.05FDD35D3A94D73514CD6F1A5B58AED53 (请注意参加签名的参数为:app_key、format、method、session、sign_method、timestamp、secret、v。其它参数不参加签名)
(4)生成签名:
32位大写MD5值->2D81422E364C783AA2998E0E612F82AA
(5)拼装HTTP请求
参数URLEncoding为UTF-8编码,然后拼装,通过浏览器访问该地址,即成功调用一次接口,如下:
https://gw-api.dangdang.com/openapi/rest?v=1.0&sign=2D81422E364C783AA2998E0E612F82AA&sign_method=md5×tamp=2013-05-06+13%3A52%3A03&app_key=2100000826&method=dangdang.item.itemid.get&format=xml&session=4ECBED3068CB782DC287FACCD52E06AB6E6F1CB4C63EF3372AC7CD88FE34C063&oit=123abcde
5. 注意事项
(1)所有的请求数据编码皆为UTF-8格式
(2)所有的响应数据编码以实际content-type返回的编码集为准(一般为gbk)
(3)请求成功时,由于各api返回节点不同,详细请参考具体api说明。
(4)系统级请求失败时,返回格式为:
<errorResponse>
<errorCode>XXX</errorCode>
<errorMessage>XXX</errorMessage>
</errorResponse>
参考错误码一览
Copyright © 当当网 2004-2012, All Rights Reserved