whatshot[2019-07-04更新] 虎绿林API:JSON Page

@Ta 01-17 12:45 8115点击

更新列表:

[2019-07-04] 添加了“用户信息扩展”功能(演示:https://hu60.cn/q.php/bbs.topic.82570.json?_uinfo=name,avatar,sign,contact ),具体见下方描述。
[2018-01-03] 域名修改为hu60.net
[2017-03-25] 添加了网页插件数据存储API,可供网页插件存储和查询自定义键值对:https://hu60.cn/q.php/bbs.topic.83603.html
[2016-12-25] 全局参数 json 更名为 _json;添加了全局参数 _content=html|ubb|json 用于选择返回内容的格式。
[2016-12-29] 添加了全局参数 _origin=*|域名,可支持浏览器中的跨站Ajax访问。为保证用户安全,跨站Ajax拒绝接受和设置任何Cookie。
[2016-12-31] 修复在JSON页面发at消息,在html页面查看,点击链接跳转到JSON页面的问题。为解决问题,原url中的bid(html或json)用占位符“{$BID}”取代,并在显示时才替换成当前页面的bid。
[2016-12-31] 在帖子页面添加了一个参数用于区分帖子到底是正序还是倒序显示的:"floorReverse": true|false。这个选项可以在用户中心被更改。未登录用户默认是true。


就在刚刚,虎绿林完成了整站的 JSON API 编写工作。

为了减少工作量,以及保证 API 和网页的一致性,虎绿林用了一种独特的方式提供 API,可能除了虎绿林,没有人用同样的方法提供API了。

我把这种方式称为 JSON Page(JSON页面),它实现的方法很简单,就是用虎绿林的主题切换功能,为网站写一个纯粹用JSON输出的主题。

效果是这样的:
https://hu60.net/q.php/index.index.json
https://hu60.net/q.php/bbs.topic.82570.json

把任何一个页面的后缀由 .html 改成 .json,就可以看到这个页面的 JSON 版本。
几乎所有页面都提供了 JSON 版本,欢迎各位用 JSON 版本来做任何事。

注意不是在.html后面加.json,而是把.html改成.json。比如首页的HTML版:
https://hu60.cn/q.php/index.index.html
首页的JSON版:
https://hu60.cn/q.php/index.index.json

JSON 版本的交互方式和网页是一样的:
比如翻页,网页是改变URL,JSON版本也是改变URL。
再比如发言,网页是 POST 提交,JSON版本也是一样,提交的参数也和网页相同,唯一的区别是提交的页面的后缀改成 .json。
再比如帖子排列的倒序正序,和html版一样也是受用户中心的选项控制(目前没有方法让未登录用户获得倒序排列)。

JSON版本可能会有错误,如果遇到问题,请及时在这个帖子反馈。


数据存储API:

可供网页插件存储和查询自定义键值对,详见 https://hu60.net/q.php/bbs.topic.83603.html


七牛云文件上传API:

可上传文件到虎绿林的七牛云存储库,供发帖使用。详见 https://hu60.cn/q.php/bbs.topic.89896.html


特殊页面:

查看登录状态、内信和@信息条数(只有json版):
http://hu60.net/q.php/user.stat.json


JSON压缩(注意,参数名由 json 变成了 _json):

用 _json=compact 参数可以得到压缩后的 JSON 结果
https://hu60.net/q.php/index.index.json?_json=compact

如果你想要把所有返回的数组都变成对象,可以用 _json=object
https://hu60.net/q.php/index.index.json?_json=object

这两个参数可以一起用,_json=compact,object


用户信息扩展:

可以用于任何返回值中包含uid或者***uid(如byuidtouid)的页面。
添加URL参数_uinfo=name,avatar,sign,contact(逗号分隔,可以删掉不需要的项目),返回值中便会多出如下成员:
_u_name_u_avatar_u_signature_u_contact

https://hu60.cn/q.php/bbs.topic.82570.json?_uinfo=name,avatar,sign,contact

...
"uid": 1,
"_u_name": "老虎会游泳",
"_u_avatar": "http://qiniu.img.hu60.cn/avatar/1.jpg?1557592687",
"_u_signature": "你好,这里是虎绿林。",
"_u_contact": "QQ 905172616 & 18502433620 & hu60.cn@gmail.com & N/A"
...

如果是***uid,则***位于字段开头,如:
https://hu60.cn/q.php/msg.index.json?_uinfo=name,avatar,sign,contact

...
"touid": 1,
"byuid": 841,
"to_u_name": "老虎会游泳",
"to_u_avatar": "http://qiniu.img.hu60.cn/avatar/1.jpg?1557592687",
"to_u_signature": "你好,这里是虎绿林。",
"to_u_contact": "QQ 905172616 & 18502433620 & hu60.cn@gmail.com & N/A",
"by_u_name": "000",
"by_u_avatar": "http://qiniu.img.hu60.cn/avatar/841.jpg",
"by_u_signature": "安静的PHPer",
"by_u_contact": "to7@foxmail.com"
...

返回内容格式选择:

https://hu60.net/q.php/bbs.topic.82570.json?_content=ubb
https://hu60.net/q.php/bbs.topic.82570.json?_content=json
https://hu60.net/q.php/bbs.topic.82570.json?_content=html

这个参数可以用来改变包含UBB的内容的格式。
支持三种格式:html、json、ubb,如果没有这个参数,默认是html。

json格式是帖子内容存储在数据库中的格式,其基本形式为:

  1. 每个UBB标记存储为一个 JSON 对象,其中包含 type 属性,记录了UBB的类型。每个类型都有各自不同的其他属性,记录了UBB的实际数据。纯文本的UBB类型为text。
  2. 帖子的所有内容从前往后依次排列构成一个 JSON 数组。

具体的解码方法参考:https://github.com/hu60t/hu60wap6/blob/master/src/class/ubbdisplay.php

注意:对内信使用 ubb 类型是不安全的。管理员删除提醒、管理员编辑提醒、管理员沉帖提醒都没有对应的UBB标记,因此这三种内容的ubb格式会得到空白内容!

此外,at消息也完全没有对应的UBB标记,因此应该使用json类型来获取at消息的机器可读数据。
at消息的json数据是非常容易解析的:
https://hu60.net/q.php/msg.index.@.json?_content=json

"content": [
    {
        "type": "atMsg",
        "uid": 15591,
        "pos": "帖子“虎绿林API:Json Page”的回复中",
        "url": "bbs.topic.82570.{$BID}",
        "msg": "@老虎会游泳,多此一举",
        "len": 60
    }
]

注意URL中的“{$BID}”,它应该被替换为当前页面的bid(如html或json)。

此外,如果聊天室的某个发言被删除,你总是会得到html类型的发言被删除提醒,无法得到ubb或json类型的提醒。


常见的数据结构:

任何操作成功都会返回:
{'success':true}

任何操作如果失败,返回的数据都会包含以下字段:
{'success':false, 'notice':'失败原因'}

网站报错之JSON版:
https://hu60.net/q.php/index.x.html
https://hu60.net/q.php/index.x.json
{
"error": "true",
"errInfo": {
"code": 1404,
"message": "页面 'index.x.json' 不存在",
"file": "/var/www/hu60.net/src/class/page.php",
"line": 137,
"trace": "#0 /var/www/hu60.net/src/q.php(59): page->load()\n#1 {main}"
}
}

要注意,网页报错可能会在任何页面发生,所以最好先检查返回的结果中是否包含error字段。如果包含,那应该是网页报错了。


登录状态保持:

向登录页的JSON版提交用户名和密码,可以获得返回的 sid 和 cookie。

如:

curl --data 'type=1&name=老虎会游泳&pass=123&go=1' https://hu60.net/q.php/user.login.json

你会得到

{
    "page": "loginPage",
    "success": false,
    "notice": "密码错误。",
    "active": null
}

如果密码正确,你就可以得到sid了。

如果你不保留 cookie,可以选择在之后的每个请求中,在网址的中间部分包含 sid 参数,如:
https://hu60.net/q.php/你的sid/bbs.topic.82570.json

注意:虎绿林不支持在GET或POST参数中包含sid,所以以下方法没有用:
https://hu60.net/q.php/bbs.topic.82570.json?sid=xxxxx


未登录、掉线与重定向:

与 html 页面一样,在 JSON Page 中未登录/掉线用户访问登录后才能查看的页面也会跳转到登录页。

比如访问 https://hu60.net/q.php/xxx/user.index.json 时,自动跳转到 https://hu60.net/q.php/xxx/user.login.json?u=user.index.json

程序设计者应该考虑到这一点,避免因此而发生未预期的错误。


跨域Ajax:

通过 _origin 参数可以指定允许跨域的域名,比如:
https://hu60.net/q.php/index.index.json?_origin=*
https://hu60.net/q.php/user.stat.json?_origin=g.cn,hu60.org&sid=xxxxxx
(_origin 参数在 html、jhtml和json等页面均可用。)

注意:一但出现 _origin 参数,虎绿林将拒绝接受或设置任何Cookie,如果你希望用户能够登录,必须按照“登录状态保持”一节所说的通过 GET、POST 或在网址中传递 sid 参数。

虎绿林通过拒绝接受任何 Cookie 保证了跨域对已经在虎绿林登录的用户是安全的,用户身份信息不会被 XSS 脚本盗用。

通过拒绝设置任何 Cookie,防止跨站应用对已经在虎绿林登录的用户造成副作用,比如在跨站应用中登录另一个帐号,在虎绿林中登录的帐号并不会改变。

回复列表(42)
  • 1
    @Ta / 2016-12-24
    留名
  • 2
    @Ta / 2016-12-24
    不懂
  • 3
    @Ta / 2016-12-24
    都是死在前端。。。
  • 4
    @Ta / 2016-12-24
    路过
  • 5
    @Ta / 2016-12-24
    层主 @小杨 于 2019-09-08 11:31 删除了该楼层。
  • 6
    @Ta / 2016-12-24
    我噗
  • 7
    @Ta / 2016-12-24
    表示之前就在想把页面的数据用js采集保存成对象 ,, 然后输出一个新的页面在把对象里的各种数据填进去    不过一直没时间去搞~
  • 8
    @Ta / 2016-12-24
  • 9
    @Ta / 2016-12-24
    @水木易安,上吧,app靠你了,你上次做的还蛮好的
  • 10
    @Ta / 2016-12-24
    帖子页面怎么不能返回UBB的形式
  • 11
    @Ta / 2016-12-25
    @net909,虎绿林的UBB解析工作非常复杂,因此由客户端自己来解析是不现实的。所以只在编辑时提供UBB,在展示时不提供。
  • 12
    @Ta / 2016-12-25
    之后可以提供选项来把相对链接变成绝对链接;不对用户输入的链接进行编码;修改at按钮调用的函数名等。
  • 13
    @Ta / 2016-12-25
    用这个写个消息机还不错!
  • 14
    @Ta / 2016-12-25
    明明就是偷懒了吧,把本来页面里的参数json打印一下
  • 15
    @Ta / 2016-12-25
    cool
  • 16
    @Ta / 2016-12-25
    @超级管理员,是啊,这个API的实现方式就是把本来页面里的参数json打印一下啊。

    @net909,说起来你们真的想要返回UBB内容吗?(返回UBB内容和返回html内容要做的事情是一样多的。因为帖子在数据库中的存储形式既不是ubb也不是html,而是php数组。)如果确实有这个需求,我可以提供。
  • 17
    @Ta / 2016-12-25
    @老虎会游泳,多此一举
  • 18
    @Ta / 2016-12-25
  • 19
    @Ta / 2016-12-25
    已经实现 json 版对用户输入的 URL 不进行编码了。
    html 版还是进行编码(从而跳转到 link.url.html)。

    之所以可以很方便的实现这个特性,是因为帖子内容的存储方式是PHP数组,每个UBB标记都被解析成一个对象,因此生成的内容可以很容易被改变。
添加新回复
回复需要登录

[聊天-公共聊天室] o:@情醉中国风,吓得我赶紧挂了电话拉黑了