Welcome Guest ( Log In | Register )

欢迎访问本站。游客仅能浏览首页新闻、版块主题、维基条目与资源信息,需登录后方可获得内容发布、话题讨论、维基编辑与资源下载等权限。若无账号请先完成注册流程。
 
搜索
 
 

Introduction

  • 返回数据一律使用 JSON 格式,XML 格式有支持计划但优先级很低
  • 请使用 HTTPS 调用接口以规避潜在的安全风险,否则可能会无法正常访问
  • 为保证安全性,API 不允许 JavaScript 跨域访问,请在服务端调用
  • 状态码统一返回 200,请自行判断数据内的 code 值,42 为正确,其余均为错误
    • 弱类型语言在比较对象值时会自动转换类型(如空值转换成 0),请切记使用全等(===)操作符
    • 返回数据内的 visitor 记录了当前访问者的用户 Id 值,0 为游客
  • 服务端形式的第三方应用请注意设置 X-Forwarded-For,以便(未来的)统计功能获取客户端的真实 IP
    • 服务端前的反向代理 / CDN(如果有)本身也应进行恰当设置,确保将真实 IP 传递给服务端
  • 问题反馈与开发建议等相关讨论请移步 T.R.O.W. API Discussion

Legal Statement

  • 一旦使用本服务,表明您已同意下述条款;若违背以下条款,本站有权随时封禁服务或采取法律措施
    1. 不得使用本服务及由此获取的本站数据进行任何违法或不正当活动
    2. 用户在本站发布或产生的数据由用户及本站共同所有,任何其他组织或个人未经授权同意,不得复制或擅改内容
    3. 特别地,不得利用本服务来进行填充商业或个人站点等任何行内容采集之实的活动
  • 在不违反上述条款的情况下,利用本服务进行盈利的行为是允许的,但需要先联系管理员进行报备并获取许可

Application Authentication

  • 先到 Manage Applications 里创建应用,每个账号最多可创建一百个应用
    1. 应用默认只有读取数据的权限,不再提供发帖等写入数据的权限
    2. 我们会不定期审核应用,若发现滥用现象,将予以降权乃至删除的处理
    3. 应用权限详情请查看 Privilege 部分
  • 访问 /stats/time 接口获取服务器当前时间 time
    • 亦可略过此步直接获取本地时间,只要与东八区时间误差在五分钟内即可
    • 接口鉴权有五分钟逾期限制,超时则必须重新获取 time 并再次计算签名
  • 使用 appkey、time 与 appsecret 生成 sign,步骤如下
    1. 对 appkey、time 和所有需要提交的参数,按参数名进行自然升序排列(数字在字母前,不区分大小写)
      • 排序前请确保所有参数值均不为空或 null(可以是 0 或 false)
      • 推荐将所有参数放到一个数组中,再对其按键值排序
      • PHP 参考代码:ksort($array, SORT_NATURAL | SORT_FLAG_CASE)
    2. 特别地,对于涉及文件上传的接口,还需作如下操作
      • 对每一个 file 参数,都构造文件名、文件大小(字节数)及文件内容 SHA1 码的拼接值
      • 参考代码:$filename.filesize($filename).sha1_file($filename)(注意这里 SHA1 需输出字符串)
      • 然后将 file 参数及其对应的拼接值,与其他常规参数一起参与排序并构造签名明文
    3. 将排序后得到的参数拼接至接口路径,构造签名明文 plaintext
      • 接口路径形如 /board/topics/list ,不含域名和参数,并以“/”开头
      • 拼接后的 plaintext 格式参考:/board/topics/list?fid=2&starter_id=4
      • PHP 中可以使用 http_build_query 方法来拼接参数,该方法生成的是 urlencode 过的字符串,因此还需要对结果再进行一次 urldecode 以得到正确的 plaintext
      • 注意本步骤拼接得到的 plaintext 只是用于生成签名的中间变量,与实际提交的接口和参数均无关
    4. 明文 plaintext 构造完毕后,对其进行如下操作以获取最终签名
      • 使用 appsecret 对 plaintext 进行 HMAC-SHA1 散列,注意此步要输出原始二进制数据
      • 对得到的二进制数据进行 Base64 编码,注意编码结果可能会包含“=”,因此需要再对其进行一次 URL 编码
      • 某些系统会将“=”编码成“%3d”(应为“%3D”),或者忽略“*”(应为“%2A”),或者将空格编码为“+”(应为“%20”),此类情况均会造成鉴权失败,请注意检查
      • 亦即,编码需要遵循 RFC 3986 规范,PHP 中推荐使用 rawurlencode 方法进行编码
      • 参考代码:rawurlencode(base64_encode(hash_hmac('sha1', $plaintext, $appsecret, true)))
    5. 最后将上述步骤得到的签名作为 sign 参数附加提交即可
  • /stats/time 外,其他所有接口都必须带有 appkey、time 和 sign 参数,否则将无法通过鉴权
    • appsecret 无需提交,请自行妥善保存,谨防外泄

API Rate Limit

  • 每个应用每小时可以发起的 API 请求数是有额度限制的,请第三方开发者酌情考虑添加缓存机制
  • HTTP 头部的 X-Rate-Limit-Remaining 信息记录了当前(最近一小时内)剩余的可用额度
  • 应用鉴权成功才会扣除请求额度,否则不扣除额度,也不显示 X-Rate-Limit-Remaining 信息
    • 特别地,应用鉴权成功但使用了无权限的接口,也会扣除额度
  • 无需应用鉴权的接口(/stats/time)是没有额度限制的,也没有 X-Rate-Limit-Remaining 信息
  • 权限越高的应用请求额度也越多,具体数目请见 Privilege 部分

Privilege

为避免滥用带来的不安全因素,即日起不再提供更高级别权限的公开API,仅提供读取接口

Mask Description Limit
1 默认级别,仅具备读取权限 1000 / hour
若申请者无特定版块的浏览权限,则就算访问者具备相关权限,也无法通过该应用来访问此特定版块

Documentation


trow/api/start.txt · 最后更改: 2018/09/12 20:53 由 inthel
 
Copyright © 2005-2019 The Ring of Wonder Time is now: 2019-11-13, 08:16