Fishroom API proposal

Changelog

• 2016.06.24 规范状态码和返回值，修正一些参数
• 2016.06.23 加入 X-TOKEN-ID, X-TOKEN-KEY header，发消息返回 JSON
• 2016.06.14 首次更新

认证

每个请求中都应该带有 X-TOKEN-ID 和 X-TOKEN-KEY 两个 header

Header	说明
X-TOKEN-ID	API token id
X-TOKEN-KEY	API token key

返回结果

所有成功的请求的返回结果都是 JSON，一个典型的 HTTP Header 如下：
（如果没有说明，下列所有 API 的返回值中均会包含这些 Header）

HTTP/1.1 200 OK
Connection: close
Content-Length: 289
Content-Type: application/json
Date: Tue, 14 Jun 2016 06:19:53 GMT
Server: nginx/1.9.10
Strict-Transport-Security: max-age=31536000

当一个请求成功时，可能返回的 HTTP 状态码有：

状态码	含义	说明
200	OK	适用于一般情况
202	Accepted	适用于发送消息的请求
204	No Content	保留

当一个请求失败时，可能返回的 HTTP 状态码有：

状态码	含义	说明
400	Bad Request	客户端未按照文档要求正确传递参数，或参数格式不正确
401	Unauthorized	请求的 Header 中没有包含认证信息，或者认证失败
404	Not Found	根据传入的参数找不到相应信息
418	I'm A TUNA	检测Fishroom状态（卖萌专用）

在此列表以外的状态码很可能产生自不可预期的服务器错误。

API list

测试 API 状态

GET https://fishroom.tuna.moe/api/status

预期返回值

Code: 418 I'm A TUNA
Body: {"status":"OK"}

监听消息流

GET https://fishroom.tuna.moe/api/messages

URL 参数

参数	说明
room	监听的聊天室名称（不给出则监听所有的聊天室）

说明

此 API 只能查询从连接建立开始收到的所有消息。
此方法返回的 Header 中附有 ETag，且 Connection 属性被设置为 keep-alive，以维持一个长连接。

预期返回值

Code: 200 OK
Body: 名为 messages 的一个 JSON 字典，其中元素的构成如下：

名称	类型	含义
botmsg	boolean	是否由机器人发出
channel	string	消息来源
content	string	消息内容
date	string	发送日期（YYYY-MM-DD）
media_url	string	媒体文件的URL（文本则此属性为空）
opt	dict	可选附加参数
mtype	string	消息类型（文本或图片等）
receiver	string	收信者（如 Telegram Group ID）
rich_text	string	用于富文本的格式化（可为null）
room	string	收到消息的 Fishroom 频道名称
sender	string	发送者在 Fishroom 的昵称
time	string	发送时间（hh:mm:ss）

测试

等待修改

发送消息

POST https://fishroom.tuna.moe/api/messages/<room>/

其中 room 为要发送信息到的聊天室名称

POST JSON

{
    "sender": "nickname", // 可选，默认值为API应用名
    "content": "message content" // 消息内容
}

预期返回值

Code: 200 OK
Body: {"message":"Success"}

测试

等待修改