API 文档

HTTP API

API 文档位于 Postman 上，项目成员可以 点击链接 加入 Postman

由于 Postman 免费版一个团队最多只有三个人，建议调整为后端一人 + 前端一人 + APP 一人，或者共享账号使用

websocket API

由于 Postman 目前可以保存 websocket API，你可以在 Team Workspace 的 OpenTreeHole-websocket 这个 Collection 下找到它们。

所有发送和接收的数据都应为 JSON 格式，对于未以 JSON 发送的数据，连接将关闭。

服务端发送的数据是多变的，但绝大多数时候，都会包含一个 message 字段以指示消息的内容。

鉴权

未鉴权的用户无法向服务端发送数据，也无法收到所有需要登录才能收到的通知推送。

鉴权方式有两种：

1. 添加与 HTTP 相同的 Authorization header
2. 将 token={{token}} 编码在 query string 中

由于原生 js 的 websocket 客户端无法添加请求头，故提供了第二种鉴权方式，考虑到生产环境中 websocket 都通过 TLS 传输，方法2理论上是安全的。

websocket 获取任务结果

由于 Django 是一个同步的 web 框架，对于高 IO 操作，后端将其放入任务队列中执行以防阻塞主线程的运行。

在任务队列中执行的任务如下：

名称
发送邮件
上传图片
通知推送

其中前两者处于 API 流程中，对这两个 API 的请求，后端会立即返回 202 Accepted 状态码，表示已将任务提交至队列。前端若需要知道任务完成情况，须连接至 wss://{{host}}/ws/notification

对于需要鉴权的 API，比如上传图片，当任务完成后会收到消息。

对于不需要鉴权的 API，比如发送邮件，当建立连接时会收到一条 {"uuid": "uuid 值"}，在访问这些 API 时需要将 uuid 加入到请求体中，这样任务完成后也能收到消息。

消息的格式如下：

字段	示例值	说明
message	上传失败，原因是......	必有
success	false	必有
data	json 数据	目前只有上传图片失败时会给出图片服务器的返回数据

websocket 获取通知

连接至 wss://{{host}}/ws/notification 以获取通知推送

数据格式

服务端发送 Message 对象

字段	示例值	说明
message_id	1
message	你的帖子被修改了
code	modify
data	数据对象	硬编码的 json 数据，具体类型请参阅下方通知场景
has_read	false
time_created	2021-10-04T19:34:03.356480+08:00

通知场景

场景	message	data	code	默认通知	备注
帖子被提及时	你在{hole}的帖子{floor}被引用了	提及你的帖子	mention	是
收藏的主题帖有新帖时	你收藏的{hole}有新回复	新增的帖子	favorite	是
用户被处罚后	你因为帖子##{instance}违规而被处罚	三个字段：level date division_id	penalty	是
帖子被修改时	你的帖子{floor}被修改了	被修改的帖子	modify	总是
被举报时	{user} 的帖子{hole}({floor})被举报了	Report 对象	report	否	仅通知管理员
用户权限发生变化时	你的权限被更改了	权限 对象	permission	总是

注：是否接收通知是可以配置的，默认的用户配置如 “默认通知” 所示，“总是” 指无论如何都会收到通知。

接收数据

连接建立时服务端会先发送一条 { "message": "未读消息"}，随后按升序依次发送用户未读的消息

发送数据

获取通知

字段	值	是否必须	说明
action	get	是
id	1	否	如有 id 则为获取单个，获取单个时不受 unread 字段影响
unread	false	否	true 为获取所有，false 为获取未读，默认为 false

返回：message 对象或 message 数组

阅读通知

字段	值	是否必须	说明
action	read	是
id	1	是

返回：message 对象

标注未读

字段	值	是否必须	说明
action	unread	是
id	1	是

返回：message 对象

清空未读

字段	值	是否必须	说明
action	clear	是

返回：

{
    "message": "所有未读消息已清空"
}