查看“BBS数据接口”的源代码

== 数据类型 ==
AttachInfo:
<source lang="javascript">
{
  "name": <string: Attachment filename>, 
  "offset:": <int: Attachment offset in post>
}
</source>

== JSONP ==
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional
|-
| jsonp || string || JSONP function name || Yes
|-
| jsoncallback || string || JSONP function name || Yes 
|}

If you want JSONP, just add '''jsonp=function''', and the result would be 
<source lang='javascript'>
function(data);
</source>

== 登录 ==
[[BBS OAuth]]

== 版面 ==
BoardInfo:
<source lang="javascript">
{
  "name": <string: Board name>,  
  "read": <Boolean: Board read?>, 
  "BM": <string: BMs>, 
  "id": <int: Board id>, 
  "total": <int: Total post count>, 
  "currentusers": <int: Current users count>, 
  "major": <string: major class>, 
  "minor": <string: minor class>, 
  "outpost": <string: may outpost>, 
  "desc": <string: description>},
  "group": <int: Group ID, or 0 if not in a group, match with id>,
  "isdir": <boolean: is a board group> [optional],
  "child_count": <int: children count of the board group> [optional]
}
</source>

* 帖子列表模式（通常以mode参数出现）：
** normal:  普通模式
** digest:  文摘模式
** mark:    被m模式
** thread:  同主题模式
** origin:  原作模式
** sticky: 置顶模式

=== 列出版面 ===
: '''GET''' /board/list
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional
|-
| session || string || Session Token || No
|-
| start || int || ID of the first post to list || Yes 
|-
| end || int || ID of the last post to list || Yes 
|-
| count || int || Number of posts to list || Yes 
|-
| group || int || Board group to list || Yes
|}
* Return value
** Success: 
<source lang="javascript">
[
  <BoardInfo: information of one board>,
  ...
]
</source>

=== 获取帖子列表 ===
: '''GET''' /board/post_list
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No
|- 
| name || string || Name of the board to list || No
|-
| mode || string || Mode of this board to list || Yes || 帖子列表模式
|-
| start || int || ID of the first post to list || Yes 
|-
| end || int || ID of the last post to list || Yes 
|-
| count || int || Number of posts to list || Yes 
|}
* Return value
** Success: 
<source lang="javascript">
[
  <PostInfo: information of one post>,
  ...
]
</source>

=== 获取同主题帖子列表 ===
: '''GET''' /board/thread_list
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No
|- 
| name || string || Name of the board to list || No
|-
| mode || string || how detailed the result should be || Yes || '''idonly'''/compact/detailed
|-
| start || int || where to start the listing || Yes ||
|-
| count || int || how many posts to list || Yes ||
|-
| tid || int || id of the thread to list || No ||
|-
| max_lines || int || (only in detailed mode) max number of lines to return || Yes ||
|}
* Return value
** mode == idonly:
** 
<source lang="javascript">
{
    result: 'ok',
    list: [
       {
          id: <int: post id>,
          xid: <int: unique post id>
       }, ...
    ]
}
</source>
** mode == compact / detailed:
<source lang="javascript">
{
    result: 'ok',
    list: [
         <same as /post/view>, ...
    ]
}
</source>

=== 清除未读标记 ===
: '''POST''' /board/clear_unread
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional
|-
| session || string || Session Token || No
|- 
| name || string || Name of the board to list, or clear everything if ignored || Yes
|-
| to || int || unique ID (xid) of the post to clear to || Yes
|}

如果不提供to参数，则清除所有。否则清楚从开始到指定帖子的未读标记。如果连name都不提供…… 那就清除所有版面未读标记！

=== 获取备忘录 ===
: '''GET''' /board/note

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional
|-
| session || string || Session Token || No
|- 
| name || string || Name of the board || No
|}


=== 获取秘密备忘录 ===
: '''GET''' /board/secnote

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional
|-
| session || string || Session Token || No
|- 
| name || string || Name of the board || No
|}

== 帖子 ==
PostInfo:
<source lang="javascript">
{
  "posttime": <time: post time>, 
  "attachflag": <int: unknown>, 
  "read": <Boolean: Post read>, 
  "title": <string: Post title>, 
  "attachment": <int: Attachment count>, 
  "owner": <string: Poster userid>, 
  "id": <int: Post id>, 
  "xid": <int: unique post ID>,
  "thread": <int: thread ID>,
  "reply_to": <int: ID of the post this post replied to>,
  "size": <int: post size>,
  "flags": [<string: one flag>, ...],
}
</source>
* flags: marked, noreply, g, deletable

PostContent:
<source lang="javascript">
{
  "picattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "otherattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "content": <string: Post content>, 
}
</source>

PostAttachInfo:
<source lang="javascript">
[
  {
    "name": <string: attachment file name>,
    "store_id": <string: ID of the storage, returned from store/new>
  },
  ...
]
</source>

=== 获取帖子 ===
: '''GET''' /post/view
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional || Choices
|-
| session || string || Session Token || No ||
|-
| id || int || ID of the post in this board || No ||
|- 
| board || string || Name of the board this post belongs to || No ||
|-
| mode || string || Mode of the board this ID corresponds to || Yes || 帖子列表模式
|-
| start || int || Start from line No. || Yes || start >= 0
|-
| count || int || Lines to fetch || Yes || count >= 0
|}
* Return value
** Success: 
<source lang="javascript">
{
  "attachlink": <string: base of attachment link. add "&a=offset" to obtain the full link.>,
  <*PostContent: content of the post>,
  <*PostInfo: information of the post>
}
</source>

=== 获取附件 ===
: '''GET''' /post/get_attach
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No
|-
| id || int || ID of the post in this board || No
|- 
| board || string || Name of the board this post belongs to || No
|-
| mode || string || Mode of the board this ID corresponds to || Yes || 帖子列表模式
|-
| offset || int || Offset of the attachment in the post, returned in "view" || No
|}
* Result value
<source lang="javascript">
{
  "content": <string: Post content encoded in Base64>, 
  "name": <string: Attachment name>
}
</source>

=== 同主题浏览 ===
: '''GET''' /post/nextid
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session token || No ||
|-
| id || int || Post ID to start search from || No ||
|-
| board || string || Board name || No ||
|-
| direction || string || Search direction || Yes || '''forward'''/backward
|-
| last_one || bool || Search for the last post || Yes || '''0'''/1
|-
| only_new || bool || Only search for new post || Yes || '''0'''/1
|-
| mode || string || how detailed the result should be || Yes || '''idonly'''/compact/detailed
|-
| max_lines || int || (only when mode=detailed) number of lines to return || Yes ||
|}
* Result
** If mode = idonly:
** {'nextid': <int: next post id in the thread>, 'nextxid': <int: next post's unique id>}
** If mode = compact/detailed: same as the result of /post/view
* Examples
** direction=forward: search for next post in the same thread
** direction=backward, last_one=1: go to the head of the thread
** direction=backward, last_one=1, only_new=1: go to the first unread post in the thread

=== 引用帖子 ===
: '''GET''' /post/quote
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No
|-
| board || string || Name of the board this post belongs to || No
|-
| id || int || ID of the post to quote || No
|- 
| xid || int || unique ID of the post to quote || No
|-
| mode || string || quote mode || Yes || '''S'''/R/N/A
|-
| index_mode || string || mode of the post list where ID belongs to || Yes || 帖子列表模式
|}
* Result
** <source lang="javascript">{"title": <string: Quoted title>, "content": <string: Quoted content>}</source>

=== 准备 ===
: '''GET''' /post/prepare
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No ||
|-
| for || string || action to prepare for || No || new
|-
| board || string || Name of the board this post belongs to || No ||
|-
| re_id || int || ID of the post to reply (for=new) || Yes ||
|- 
| re_xid || int || unique ID of the post to reply (for=new) || Yes ||
|-
| re_mode || string || mode of the post list where re_id belongs to (for=new) || Yes || 帖子列表模式
|-
| anonymous || boolean || create anonymous post (for=new) || Yes || '''0'''(no)/1(yes)
|-
| attachments || JSON encoded PostAttachInfo || attachments info || Yes ||
|}

result: <source lang="javascript">{"error": {<string: error>: 1}}</source>
如果没错误，那后面的hash是空的。

=== 发帖/回帖 ===
: '''POST''' /post/new
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No ||
|-
| board || string || Name of the board this post belongs to || No ||
|-
| re_id || int || ID of the post to reply || Yes ||
|- 
| re_xid || int || unique ID of the post to reply || Yes ||
|-
| re_mode || string || mode of the post list where re_id belongs to || Yes || 帖子列表模式
|-
| title || string || title of the post || No ||
|-
| content || string || content of the post || No ||
|-
| signature_id || int || No. of qmd to use || Yes || <0(random)/'''0'''(none)/>0(qmd #)
|-
| anonymous || boolean || create anonymous post || Yes || '''0'''(no)/1(yes)
|-
| mailback || boolean || require replies to be mailed back || Yes || '''0'''(no)/1(yes)
|-
| attachments || JSON encoded PostAttachInfo || attachments info || Yes ||
|}

发帖的话，id和xid可以忽略。回帖的话，需要提供id和xid。

=== 删帖 ===
: '''POST''' /post/delete
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No ||
|-
| board || string || Name of the board this post belongs to || No ||
|-
| id || int || ID of the post to delete || Yes ||
|- 
| xid || int || unique ID of the post to delete || No ||
|-
| mode || string || mode of the post list where id belongs to || Yes || 帖子列表模式
|}

xid是必须的，用于唯一定位帖子。id不是必需的。
每个人可以删自己的贴，版主可以删别人的贴。

=== 编辑 ===
: '''POST''' /post/edit
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No ||
|-
| board || string || Name of the board this post belongs to || No ||
|-
| id || int || ID of the post to edit || Yes ||
|- 
| xid || int || unique ID of the post to edit || No ||
|-
| mode || string || mode of the post list where id belongs to || Yes || 帖子列表模式
|-
| title || string || new title || Yes || 如果没有则不变
|-
| content || string || new content || Yes || 如果没有则不变
|-
| new_attachments || JSON encoded PostAttachInfo || new attachments info || Yes || 新的附件列表，参见发贴
|-
| del_attachments || array<int> || attachments to remove || Yes || 要删除的附件编号，从0开始
|}

xid是必须的，用于唯一定位帖子。id不是必需的。
每个人可以编辑自己的贴，版主可以编辑别人的贴。

=== 搜索 ===
: '''GET''' /post/search
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No ||
|-
| board || string || Name of the board this post belongs to || No ||
|-
| from || int || search from this post || Yes || 默认从头开始
|-
| forward || int || search forward || Yes || 0/1，默认向前搜索(1)
|-
| count || int || max number of search results || Yes || 默认返回一个结果
|-
| query || JSON of search query || search query || No || 格式参见下文
|}

query是一个表达式，基本形式为：
[<op>, <arg1>, <arg2>, ...]
其中op为操作符。目前支持：
* 逻辑操作符，每个参数都是一个表达式
** or: 取所有参数结果的或
** and: 取所有参数结果的与
** not: 取所有参数结果的非，只能有一个参数
** 样例
*** ['or', <expr1>, <expr2>, <expr3>]
*** ['not', <expr>]
* 字符串域匹配，有一个参数，为一个正则表达式
** author: 匹配作者
** title: 匹配标题
** content: 匹配内容
** 样例
*** ['author', 'henryhu']
*** ['title', 'hell.+orld']
* 标记匹配，没有参数
** m: 被m帖子
** g: 收精帖子
** noreply: 不可回复帖子
** has_attach: 有附件
** 样例: ['m']
* 整数域匹配，第一个参数为域名，第二个参数为比较值
** 操作符
*** ge: 大于等于
*** le: 小于等于
*** eq: 等于
** 域名
*** posttime: 发帖时间
*** thread: 主题编号，主题贴xid
*** size: 帖子大小
** 样例
*** ['ge', 'posttime', <time, UTC+8 seconds>]
*** ['eq', 'thread', 1234]

== 收藏夹 ==

FavBoardEntry:
<source lang="javascript">
{
  "index": <int: Index in favboard>, 
  "binfo": <BoardInfo: board info>, 
  "father": <int: Parent index in favboard, -1 for root entry>, 
  "type": <string: Type of this entry, "board"/"dir">
}
</source>

=== 列出收藏夹 ===

: '''GET''' /favboard/list
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|- 
| father || int || Parent directory of boards to list || Yes
|-
| start || int || ID of the first entry to list || Yes 
|-
| end || int || ID of the last entry to list || Yes 
|-
| count || int || Number of entries to list || Yes 
|}
* Return value
** Success: 
<source lang="javascript">
[
  FavBoardEntry,
  ...
]
</source>

=== 列出某个项目的所有祖先项目 ===

: '''GET''' /favboard/dirnames
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|- 
| index || int || Index of the entry || No
|}
* Return value
** Success: 
<source lang="javascript">
[
  FavBoardEntry, // the current entry
  FavBoardEntry, // its father
  FavBoardEntry, // its grandfather
  ...
]
</source>

== 会话 ==

=== 验证会话 ===
: '''GET''' /session/verify

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|}

== 精华区 ==
DigestItem:
<source lang="javascript">
{
  'mtitle': <string: menu title when listing children of this item>,
  'title': <string: title of this item>,
  'attach': <int: attachment position or attachment flag, with attachment <-> != 0>,
  'mtime': <int: modification time>,
  'type': <string: item type. can be file/dir/link/other>,
  'id': <int: item index, start from 1>,
  // these items only appear if type == link
  'host': <string: link host>,
  'post': <int: link port>
}
</source>

=== 列出目录 ===

: '''GET''' /digest/list

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|-
| board || string || Board name of the digest. If not present, start from the Digest menu. || Yes
|-
| route || string || Route to the directory. Like x-1-2-3 || No
|-
| start || int || Number of the first item || Yes
|-
| end || int || Number of the last item || Yes
|}

Result: <source lang="javascript">
{
  'parent': <DigestItem: information of the directory>,
  'count': <int: number of items returned>,
  'items': [
    <DigestItem: information of one item>,
    ...
  ]
}
</source>

=== 获取帖子 ===

: '''GET''' /digest/view

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|-
| board || string || Board name of the digest. If not present, start from the Digest menu. || Yes
|-
| route || string || Route to the post. Like x-1-2-3 || No
|}

Result: <source lang="javascript">
{
  'item': <DigestItem: information of the post item>,
  <*PostContent: content of the post>,
  'attachlink': <string: URL of the page showing attachments. add '&a=offset' for individual attachment>
}
</source>

== 用户 ==
=== 获取用户信息 ===
: '''GET''' /user/query
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|-
| id || string || ID of user to query, omit to query yourself || Yes
|}

=== 获取用户详细信息 ===
: '''GET''' /user/detail
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|}

=== 获取默认签名档编号 ===
: '''GET''' /user/signature_id
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional 
|-
| session || string || Session Token || No
|}
* Return value: <source lang="javascript">
{"signature_id": <int: default signature id>}
</source>

=== 注册新用户 ===
: '''POST''' /user/register
{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional
|-
| username || string || User ID || No
|-
| password || string || Password || No
|-
| nick || string || Nick name || No
|-
| email || string || Email || No
|-
| realname || string || Real name || No
|-
| address || string || Address || No
|-
| birthyear || int || Birth year || No
|-
| birthmonth || int || Birth month || No
|-
| birthday || int || Birth day || No
|-
| gender || string || Gender (F/M) || No
|-
| selfintro || string || Self Introduction || Yes
|-
| phone || string || Contact information || No
|-
| career || string || Class information || No
|}
* Return value: <source lang="javascript">
{"result": "ok"}
</source>

== 存储 ==
主要是用来上传文件，随后可以用于贴附件。

=== 上传文件 ===
: '''POST''' /store/new

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || Session Token || No ||
|-
| item || string || Storage item type || No || attachment
|-
| content || string || Base64-encoded content || No ||
|}

* Return value: <source lang="javascript">
{"id": <string: ID of the item created>}
</source>

== 邮箱 ==
MailInfo:
<source lang="javascript">
{
  "posttime": <time: post time>, 
  "attachflag": <int: unknown>, 
  "read": <boolean: read/unread>, 
  "title": <string: Post title>, 
  "attachment": <int: attachment count>, 
  "owner": <string: mailer userid>, 
  "id": <int: mail id>, 
  "flags": [<string: one flag>, ...]
}
</source>
* flags: marked, replied, forwarded

MailContent:
<source lang="javascript">
{
  "picattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "otherattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "content": <string: mail content>
}
</source>

=== 列出邮件 ===
: '''GET''' /mail/list

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || session token || no ||
|-
| folder || string || which folder to list || yes || '''inbox'''/sent
|-
| start || int || first mail index, start from 1 || yes
|-
| end || int || last mail index || yes
|-
| count || int || number of mails to list || yes
|}

* Return value:
<source lang="javascript">
{
    "start": <int: first mail index>,
    "end":   <int: last mail index>,
    "mails": [
        <MailInfo: information of one mail>,
        ...
    ]
}
</source>

=== 阅读邮件 ===
: '''GET''' /mail/view

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || session token || no ||
|-
| folder || string || which folder to list || yes || '''inbox'''/sent
|-
| index || int || mail index, start from 1 || yes
|}
* Return value:
<source lang="javascript">
{
    <*MailContent: content of one mail>,
    <*MailInfo: information of one mail>
}
</source>

=== 引用邮件 ===
: '''GET''' /mail/quote

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || session token || no ||
|-
| folder || string || the folder of the quoted mail || yes || '''inbox'''/sent
|-
| index || int || mail index, start from 1 || yes
|-
| mode || string || quote mode, same as post/quote || yes || '''S'''/R/N/A
|}
* Return value:
<source lang="javascript">
{
    "title": <string: quoted title>,
    "content": <string: quoted content>
}
</source>
引用某个邮件箱里的某封邮件，可选引用模式。

=== 发邮件 ===
: '''POST''' /mail/send

{| class="wikitable"
|-
! Parameter !! Type !! Description !! Optional !! Choices
|-
| session || string || session token || no ||
|-
| to || string || receiver id || no ||
|-
| title || string || mail title || no ||
|-
| content || string || mail content || no ||
|-
| signature_id || int || signature id || yes || '''0(none)'''/-1(random)/>0
|-
| save_in_sent || int || save the mail in the sent box || yes || '''1'''/0
|}
* Return value:
<source lang="javascript">
{"result": "ok"}
</source>
发邮件，可选是否存发件箱。
如果需要引用邮件，请先调用/mail/quote。