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
      • 接口路径形如 /users/login ,不含域名和参数,并以“/”开头
      • 拼接后的 plaintext 格式参考:/users/login?uname=1&ucode=test
      • 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 无需提交,请自行妥善保存,谨防外泄

User Authentication

  • 用户可到 Manage Specific Code 里设置第三方应用密码以保护站点密码安全
    1. 必须设置应用密码才能登录第三方应用
    2. 设置时需要提供相应应用的 appkey,且不推荐使用站点密码作为应用密码
  • 开发者使用 /users/login 接口验证用户提交的 uid 与 ucode,获取 utoken 并存储于本地
    1. 若验证失败,请自行提示用户到本站设置第三方应用密码
    2. 也可引导用户直接打开第三方密码应用页面进行相关操作,链接格式如下
  • 验证用户时在提交请求中附加 uid 与 utoken 参数即可,不应再要求用户输入 ucode
  • 若省略参数或校验失败,则用户身份与权限均视为等同于 Guest
  • 之所以不使用 OAuth 等常见解决方案,主要是因为第三方应用密码机制更加简洁明了且通用性良好

API Rate Limit

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

Privilege

Mask Description Limit
1 默认级别,仅具备读取权限 1000 / hour
若申请者无特定版块的浏览权限,则就算访问者具备相关权限,也无法通过该应用来访问此特定版块
3 在默认级别的基础上增加了发帖私信等写权限 2000 / hour
应用申请者必须为私信收发双方中的任一方,以免申请者利用该权限以第三者身份窥视他人私信
依然受上一级别版块权限约束的限制
开发者如需提权到此级别,请联系管理员提交申请
7 在前两个级别的基础上增加了注册账号与直接使用论坛账号密码登录的权限 4000 / hour
不再受版块权限约束与私信收发双方约束等限制
仅在审核后有限提供给信誉度高、影响力大的第三方应用使用
15 除具备前述级别的所有权限之外,还可查看用户碎晶数量并请求使用 8000 / hour
仅供 T.R.O.W. 旗下站点及官方应用使用

Documentation


trow/api/start.txt · 最后更改: 2016/12/14 13:31 由 inthel
 
Copyright © 2005-2017 The Ring of Wonder Time is now: 2017-03-25, 17:39