BBS数据接口

数据类型

AttachInfo:

{
  "name": <string: Attachment filename>, 
  "offset:": <int: Attachment offset in post>
}

JSONP

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

function(data);

登录

BBS OAuth

版面

BoardInfo:

{
  "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]
}

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

列出版面

GET /board/list

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:

[
  <BoardInfo: information of one board>,
  ...
]

获取帖子列表

GET /board/post_list

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:

[
  <PostInfo: information of one post>,
  ...
]

获取同主题帖子列表

GET /board/thread_list

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:

{
    result: 'ok',
    list: [
       {
          id: <int: post id>,
          xid: <int: unique post id>
       }, ...
    ]
}

• • mode == compact / detailed:

{
    result: 'ok',
    list: [
         <same as /post/view>, ...
    ]
}

清除未读标记

POST /board/clear_unread

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

Parameter	Type	Description	Optional
session	string	Session Token	No
name	string	Name of the board	No

获取秘密备忘录

GET /board/secnote

Parameter	Type	Description	Optional
session	string	Session Token	No
name	string	Name of the board	No

帖子

PostInfo:

{
  "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>, ...],
}

• flags: marked, noreply, g, deletable

PostContent:

{
  "picattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "otherattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "content": <string: Post content>, 
}

PostAttachInfo:

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

获取帖子

GET /post/view

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:

{
  "attachlink": <string: base of attachment link. add "&a=offset" to obtain the full link.>,
  <*PostContent: content of the post>,
  <*PostInfo: information of the post>
}

获取附件

GET /post/get_attach

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

{
  "content": <string: Post content encoded in Base64>, 
  "name": <string: Attachment name>
}

同主题浏览

GET /post/nextid

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

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

  • {"title": <string: Quoted title>, "content": <string: Quoted content>}
    

准备

GET /post/prepare

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:

{"error": {<string: error>: 1}}

如果没错误，那后面的hash是空的。

发帖/回帖

POST /post/new

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

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

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

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:

{
  "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">
}

列出收藏夹

GET /favboard/list

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:

[
  FavBoardEntry,
  ...
]

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

GET /favboard/dirnames

Parameter	Type	Description	Optional
session	string	Session Token	No
index	int	Index of the entry	No

• Return value
  • Success:

[
  FavBoardEntry, // the current entry
  FavBoardEntry, // its father
  FavBoardEntry, // its grandfather
  ...
]

会话

验证会话

GET /session/verify

Parameter	Type	Description	Optional
session	string	Session Token	No

精华区

DigestItem:

{
  '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>
}

列出目录

GET /digest/list

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:

{
  'parent': <DigestItem: information of the directory>,
  'count': <int: number of items returned>,
  'items': [
    <DigestItem: information of one item>,
    ...
  ]
}

获取帖子

GET /digest/view

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:

{
  '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>
}

用户

获取用户信息

GET /user/query

Parameter	Type	Description	Optional
session	string	Session Token	No
id	string	ID of user to query, omit to query yourself	Yes

获取用户详细信息

GET /user/detail

Parameter	Type	Description	Optional
session	string	Session Token	No

获取默认签名档编号

GET /user/signature_id

Parameter	Type	Description	Optional
session	string	Session Token	No

• Return value:

  {"signature_id": <int: default signature id>}
  

注册新用户

POST /user/register

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:

  {"result": "ok"}
  

存储

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

上传文件

POST /store/new

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:

  {"id": <string: ID of the item created>}
  

邮箱

MailInfo:

{
  "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>, ...]
}

• flags: marked, replied, forwarded

MailContent:

{
  "picattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "otherattach": [
    <AttachInfo: information of one attachment>,
    ...
  ], 
  "content": <string: mail content>
}

列出邮件

GET /mail/list

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:

{
    "start": <int: first mail index>,
    "end":   <int: last mail index>,
    "mails": [
        <MailInfo: information of one mail>,
        ...
    ]
}

阅读邮件

GET /mail/view

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:

{
    <*MailContent: content of one mail>,
    <*MailInfo: information of one mail>
}

引用邮件

GET /mail/quote

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:

{
    "title": <string: quoted title>,
    "content": <string: quoted content>
}

引用某个邮件箱里的某封邮件，可选引用模式。

发邮件

POST /mail/send

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:

{"result": "ok"}

发邮件，可选是否存发件箱。 如果需要引用邮件，请先调用/mail/quote。