WiTOWN开放平台接口文档V1.1.docxVIP

WiTOWN开放平台接口文档 版本日期初稿V1.02013/12/10支持微信url认证V1.12014/02/11 http调用方式详解 以下主要说明HTTP 方式调用API原理,您看到此文档时，您应该已经拿到了appKey和secret，appKey是一串数字，用来标识您的应用，secret是32位的字符串，用来对请求参数进行签名（服务器会校验签名以防攻击），这两个参数都是很重要的，务必做好备份，以下将会解释它们的用途。 调用介绍 作为WiTOWN数据插槽，只要用户按照WiTOWN的规范拼装一个正确的URL，通过HTTP请求，就能够拿到用户自己需要的数据。WiTOWN API 采用 REST 风格，支持 http 协议请求的程序语言，均可调用WiTOWN API，例如php、C#、asp、java、delphi 等。 调用入口 环境地址，即调用接口(API)时，都通过访问该地址，来获取该接口需要获取的数据 正式环境：/router 沙箱环境：/router 调用参数 调用API ，必须传入系统参数（所有API都需要的参数）和应用参数（某API特定的参数）。系统参数详细介绍如下；应用参数由于不同 API 各自不同，这里以 HYPERLINK /apidoc/api.htm?path=cid:1-apiId:21349 \t _self ?user.get?为例说明，更多请参考 HYPERLINK /doc/category_list.htm?id=102 \t _self 具体的API。 1）系统参数 名称类型是否必须描述methodstringYAPI接口名称messageFormatstringN可选，指定响应格式。默认json,目前支持格式为json ，xmlappKeystringY分配给应用的AppKey ，创建应用时可获得vstringYAPI协议版本，目前为:1.0。signstringY对 API 输入参数进行签名获得，详细参考如下?3、签名signlocalestringN国际化支持，默认为zh_CN，如需返回英文错误信息请使用ensessionIdstringN分配给用户的SessionKey(或 Access Token），通过登陆授权获取，方法参考 HYPERLINK /doc/detail.htm?id=101423 \t _self 用户授权介绍?。API 文档上 “API用户授权类型” 标识为“需要”的，调用时均要传该参数2）应用参数 名称类型是否必须描述userIdstringY用户id，32位3）签名sign 调用API 时需要对请求参数进行签名验证，服务器也会对该请求参数进行验证是否合法,如不合法则拒绝此次请求。方法如下：????? 根据参数名称（除签名和图片）将所有请求参数按照字母先后顺序排序:key + value .... key + value????? 例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1，参数名和参数值链接后，得到拼装字符串bar2baz3foo1????? 系统使用SHA1散列方式:????? sha1：将secret拼接到参数字符串头、尾进行sha1加密后，再转化成大写，格式是： uppercase (byte2hex(sha1(secretkey1value1key2value2...secret) )????? 注：hex为自定义方法(二进制转十六进制字符串)，我们需要的是32位的大写字符串，图片参数不用加入签名中 通用响应结果 调用API后，会返回响应结果（根据传入的messageFormat返回json或xml格式），其中通用的响应结果如下（其他响应结果为业务结果）： 名称类型是否必须描述successbooleanY接口调用是否成功，true成功，false失败codeintY失败时的错误码msgstringY失败时的错误信息subErrorCodestringN失败时的详细错误码subErrorMsgstringN失败时的详细错误信息code和msg表示粗略的错误信息； subErrorCode和subErrorMsg不一定存在，如果存在则表示更具体的错误信息。 调用示例 调用示例 调用API：user.get?，应用参数userId返回01234567890123456789012345678912，使用SHA1加密，因为各语言语法不一致，以下实例只体现逻辑。为便于说明，假设 appKey=t