menu MDClub API 文档

MDClub API 文档

MDClub 是一个 Material Design 风格的社区应用。

接口文档说明

GETPUTDELETE 请求均符合幂等性。

注意:请不要在官方的体验社区进行 API 测试,否则将直接封号。

使用详解

REST API 可以让你用任何支持 HTTP 请求的设备来与 MDClub 的服务端进行交互,你可以使用 REST API 做很多事情,例如:

Base URL

Base URL 为你的 MDClub 项目的首页网址。

例如你的 MDClub 项目的首页为 https://mdclub.org,你需要调用文档中的 /api/questions 接口时,需要在前面加上你的首页网址,即你调用的 URL 应该为 https://mdclub.org/api/question

请求格式

对于 POST、PUT 和 PATCH 请求,请求体的格式为 JSON 格式,而且 HTTP header 的 Content-Type 需要设置为 application/json

对于包含文件上传的请求,请求体格式为 form-data,而且 HTTP header 的 Content-Type 需要设置为 multipart/form-data

响应格式

响应格式统一为 JSON 格式。

请求成功时,响应中的 code 为 0,响应格式为:

{
  "code": 0,
  "data": {}
}

若响应为列表数据,可能还会包含分页信息,格式如下:

{
  "code": 0,
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 15,
    "previous": null,
    "next": 2,
    "total": 124,
    "pages": 9
  }
}

若请求失败,则响应中的 code 大于 0,具体错误代码表示的含义参见下面的 错误代码,此时响应格式为:

{
  "code": 100000,
  "message": "错误描述",
  "extra_message": "额外的错误描述(该字段不一定存在)",
  "captcha_token": "验证码的 token(该字段不一定存在,若存在该字段,则下次调用该接口时需要用户输入验证码)",
  "captcha_image": "验证码的 base64 格式的图片(该字段不一定存在,若存在该字段,则下次调用该接口时需要用户输入验证码)",
  "errors": {
    "additionalProp1": "提交含多个字段的表单时,验证失败会存在 errors 字段,键名为错误字段名,键值为错误描述",
    "additionalProp2": "同上"
  }
}

用户登录

用户登录时需要调用 POST /api/tokens 接口,该接口的响应中会包含 token 字段。

保持用户登录状态有以下两种方式:

  1. 在 HTTP header 中添加 token 参数,参数的值即为调用 /api/tokens 接口时返回的 token 字段。
  2. 在 Cookie 中添加 token 参数,参数的值即为调用 /api/tokens 接口时返回的 token 字段。

以上两种方式都能实现保持用户登录状态,若在 HTTP header 中和 Cookie 中都添加了 token 参数,则将以 HTTP header 中的为准。

token 是具有有效期的,用户在有效期内调用任意接口时,将自动续期,确保用户不需要频繁进行登录;若用户长时间未调用接口,则 token 可能会过期,即调用接口时返回“用户未登录”时,需要重新进行登录。

HTTP 方法重写

MDClub 的 Restful API 使用了 GETPOSTPUTPATCHDELETE 请求方式,然而部分老旧的浏览器、或者部分小程序平台不支持其中部分请求方式。MDClub 支持通过 X-HTTP-Method-Override 重写请求方式。

如果你需要在不支持 PUTPATCHDELETE 请求的平台中调用 MDClub 的 API,你需要在请求头中添加 X-HTTP-Method-Override 属性来重写请求方式。对于 PUTPATCH 请求,属性值设置为 POST,对于 DELETE 请求,属性值设置为 GET,对于 GETPOST 请求,则无需添加该属性。

错误代码

错误代码 错误说明
100000 服务器错误
100001 系统维护中
100002 IP 请求超过上限
100003 用户请求超过上限
100004 接口不存在
100005 该接口不支持此 HTTP METHOD
100006 请求参数的 json 格式错误
100007 系统安装失败
200001 字段验证失败
200002 邮件发送失败
200003 邮件验证码已失效
200004 图片上传失败
200005 指定图片不存在
200006 投票类型只能是 up、down 中的一个
201001 用户未登录
201002 需要管理员权限
201003 指定用户不存在
201004 目标用户不存在
201005 该用户已被禁用
201006 账号或密码错误
201007 头像上传失败
201008 封面上传失败
201009 不能关注你自己
202001 指定提问不存在
202002 提问发表后即无法编辑
202003 仅提问作者可以编辑提问
202004 已超过可编辑的时间
202005 该提问下已有回答,不允许编辑
202006 该提问下已有评论,不允许编辑
202007 提问发表后即无法删除
202008 仅提问作者可以删除提问
202009 已超过可删除的时间
202010 该提问下已有回答,不允许删除
202011 该提问下已有评论,不允许删除
203001 指定回答不存在
203002 回答发表后即无法编辑
203003 仅回答的作者可以编辑回答
203004 已超过可编辑的时间
203005 该回答下已有评论,不允许编辑
203006 回答发表后即无法删除
203007 仅回答的作者可以删除回答
203008 已超过可删除的时间
203009 该回答下已有评论,不允许删除
204001 指定的评论不存在
204002 评论发表后即无法编辑
204003 仅评论的作者可以编辑评论
204004 已超过可编辑时间
204005 评论发表后即无法删除
204006 仅评论的作者可以删除评论
204007 已超过可删除时间
205001 指定话题不存在
205002 话题封面上传失败
206001 指定文章不存在
206002 文章发表后即无法编辑
206003 仅文章作者可以编辑文章
206004 已超过可编辑时间
206005 该文章下已有评论,不允许编辑
206006 文章发表后即无法删除
206007 仅文章作者可以删除文章
206008 已超过可删除时间
206009 该文章下已有评论,不允许删除
207001 指定举报不存在
207002 举报目标不存在
207003 不能重复举报
208001 指定通知不存在

接口列表

身份验证

URL HTTP 描述
/api/tokens POST 生成 Token

系统设置

URL HTTP 描述
/api/options GET 获取站点全局设置参数
/api/options PATCH 🔐更新站点全局设置

用户

URL HTTP 描述
/api/user/answers GET 🔑获取当前登录用户发表的回答
/api/user/articles GET 🔑获取当前登录用户发表的文章
/api/user/avatar POST 🔑上传当前登录用户的头像
/api/user/avatar DELETE 🔑删除当前登录用户的头像,并重置为默认头像
/api/user/comments GET 🔑获取当前登录用户发表的评论
/api/user/cover POST 🔑上传当前登录用户的封面
/api/user/cover DELETE 🔑删除当前登录用户的封面,并重置为默认封面
/api/user/followees GET 🔑获取当前登录用户关注的用户
/api/user/followers GET 🔑获取当前登录用户的关注者
/api/user/following_articles GET 🔑获取登录用户关注的文章
/api/user/following_questions GET 🔑获取登录用户关注的提问
/api/user/following_topics GET 🔑获取登录用户关注的话题
/api/user/password/email POST 发送重置密码邮箱验证码
/api/user/password PUT 验证邮箱并更新密码
/api/user/questions GET 🔑获取登录用户发表的提问
/api/user/register/email POST 发送注册邮箱验证码
/api/user GET 🔑获取当前登录用户的信息
/api/user PATCH 🔑更新当前登录用户信息
/api/users GET 获取用户列表
/api/users POST 验证邮箱并创建账号
/api/users/{user_ids}/disable POST 🔐批量禁用用户
/api/users/{user_ids}/enable POST 🔐批量恢复用户
/api/users/{user_id}/answers GET 获取指定用户发表的回答
/api/users/{user_id}/articles GET 获取指定用户发表的文章
/api/users/{user_id}/avatar DELETE 🔐删除指定用户的头像,并重置为默认头像
/api/users/{user_id}/comments GET 获取指定用户发表的评论
/api/users/{user_id}/cover DELETE 🔐删除指定用户的封面,并重置为默认封面
/api/users/{user_id}/disable POST 🔐禁用指定用户
/api/users/{user_id}/enable POST 🔐恢复指定用户
/api/users/{user_id}/followees GET 获取指定用户关注的用户列表
/api/users/{user_id}/followers GET 获取指定用户的关注者
/api/users/{user_id}/followers POST 🔑添加关注
/api/users/{user_id}/followers DELETE 🔑取消关注
/api/users/{user_id}/following_articles GET 获取指定用户关注的文章列表
/api/users/{user_id}/following_questions GET 获取指定用户关注的提问列表
/api/users/{user_id}/following_topics GET 获取指定用户关注的话题列表
/api/users/{user_id}/questions GET 获取指定用户发表的提问
/api/users/{user_id} GET 获取指定用户信息
/api/users/{user_id} PATCH 🔐更新指定用户信息

话题

URL HTTP 描述
/api/topics GET 获取全部话题
/api/topics POST 🔐发布话题
/api/topics/{topic_ids}/trash POST 🔐批量把话题放入回收站
/api/topics/{topic_ids}/untrash POST 🔐批量把话题移出回收站
/api/topics/{topic_ids} DELETE 🔐批量删除话题
/api/topics/{topic_id}/articles GET 获取指定话题下的文章
/api/topics/{topic_id}/followers GET 获取指定话题的关注者
/api/topics/{topic_id}/followers POST 🔑关注指定话题
/api/topics/{topic_id}/followers DELETE 🔑取消关注指定话题
/api/topics/{topic_id}/questions GET 获取指定话题下的提问
/api/topics/{topic_id}/trash POST 🔐把话题放入回收站
/api/topics/{topic_id}/untrash POST 🔐把话题移出回收站
/api/topics/{topic_id} GET 获取指定话题信息
/api/topics/{topic_id} POST 🔐更新话题信息
/api/topics/{topic_id} DELETE 🔐删除话题

提问

URL HTTP 描述
/api/questions GET 获取提问列表
/api/questions POST 🔑发表提问
/api/questions/{question_ids}/trash POST 🔐批量把提问放入回收站
/api/questions/{question_ids}/untrash POST 🔐批量把提问移出回收站
/api/questions/{question_ids} DELETE 🔐批量删除提问
/api/questions/{question_id}/answers GET 获取指定提问下的回答
/api/questions/{question_id}/answers POST 🔑在指定提问下发表回答
/api/questions/{question_id}/comments GET 获取指定提问的评论
/api/questions/{question_id}/comments POST 🔑在指定提问下发表评论
/api/questions/{question_id}/followers GET 获取指定提问的关注者
/api/questions/{question_id}/followers POST 🔑添加关注
/api/questions/{question_id}/followers DELETE 🔑取消关注
/api/questions/{question_id}/trash POST 🔐把提问放入回收站
/api/questions/{question_id}/untrash POST 🔐把提问移出回收站
/api/questions/{question_id}/voters GET 获取提问的投票者
/api/questions/{question_id}/voters POST 🔑为提问投票
/api/questions/{question_id}/voters DELETE 🔑取消为提问的投票
/api/questions/{question_id} GET 获取指定提问信息
/api/questions/{question_id} PATCH 🔑更新提问信息
/api/questions/{question_id} DELETE 🔑删除提问

回答

URL HTTP 描述
/api/answers GET 🔐获取回答列表
/api/answers/{answer_ids}/trash POST 🔐批量把回答放入回收站
/api/answers/{answer_ids}/untrash POST 🔐批量把回答移出回收站
/api/answers/{answer_ids} DELETE 🔐批量删除回答
/api/answers/{answer_id}/comments GET 获取指定回答的评论
/api/answers/{answer_id}/comments POST 在指定回答下发表评论
/api/answers/{answer_id}/trash POST 🔐把回答放入回收站
/api/answers/{answer_id}/untrash POST 🔐把回答移出回收站
/api/answers/{answer_id}/voters GET 获取回答的投票者
/api/answers/{answer_id}/voters POST 🔑为回答投票
/api/answers/{answer_id}/voters DELETE 🔑取消为回答的投票
/api/answers/{answer_id} GET 获取回答详情
/api/answers/{answer_id} PATCH 🔑修改回答信息
/api/answers/{answer_id} DELETE 🔑删除回答

文章

URL HTTP 描述
/api/articles GET 获取文章列表
/api/articles POST 🔑发表文章
/api/articles/{article_ids}/trash POST 🔐批量把文章放入回收站
/api/articles/{article_ids}/untrash POST 🔐批量把文章移出回收站
/api/articles/{article_ids} DELETE 🔐批量删除文章
/api/articles/{article_id}/comments GET 获取指定文章的评论列表
/api/articles/{article_id}/comments POST 🔑在指定文章下发表评论
/api/articles/{article_id}/followers GET 获取指定文章的关注者
/api/articles/{article_id}/followers POST 🔑添加关注
/api/articles/{article_id}/followers DELETE 🔑取消关注
/api/articles/{article_id}/trash POST 🔐把文章放入回收站
/api/articles/{article_id}/untrash POST 🔐把文章移出回收站
/api/articles/{article_id}/voters GET 获取文章的投票者
/api/articles/{article_id}/voters POST 🔑为文章投票
/api/articles/{article_id}/voters DELETE 🔑取消为文章的投票
/api/articles/{article_id} GET 获取指定文章信息
/api/articles/{article_id} PATCH 🔑更新文章信息
/api/articles/{article_id} DELETE 🔑删除文章

评论

URL HTTP 描述
/api/comments GET 🔐获取所有评论
/api/comments/{comment_ids}/trash POST 🔐批量把评论放入回收站
/api/comments/{comment_ids}/untrash POST 🔐批量把评论移出回收站
/api/comments/{comment_ids} DELETE 🔐批量删除评论
/api/comments/{comment_id}/replies GET 获取指定评论的回复
/api/comments/{comment_id}/replies POST 🔑在指定评论下发表回复
/api/comments/{comment_id}/trash POST 🔐把评论放入回收站
/api/comments/{comment_id}/untrash POST 🔐把评论移出回收站
/api/comments/{comment_id}/voters GET 获取评论的投票者
/api/comments/{comment_id}/voters POST 🔑为评论投票
/api/comments/{comment_id}/voters DELETE 🔑取消为评论的投票
/api/comments/{comment_id} GET 获取评论详情
/api/comments/{comment_id} PATCH 🔑修改评论
/api/comments/{comment_id} DELETE 🔑删除评论

举报

URL HTTP 描述
/api/reports GET 🔐获取被举报的内容列表
/api/reports/{report_targets} DELETE 🔐批量删除举报
/api/reports/{reportable_type}:{reportable_id} GET 🔐获取被举报内容的举报详情
/api/reports/{reportable_type}:{reportable_id} POST 🔑添加举报
/api/reports/{reportable_type}:{reportable_id} DELETE 🔐删除举报

私信

URL HTTP 描述

通知

URL HTTP 描述
/api/notifications/count GET 🔑获取未读通知数量
/api/notifications/read POST 🔑把所有通知标记为已读
/api/notifications GET 🔑获取通知列表
/api/notifications DELETE 🔑删除所有通知
/api/notifications/{notification_ids}/read POST 🔑批量把通知标记为已读
/api/notifications/{notification_ids} DELETE 🔑批量删除通知
/api/notifications/{notification_id}/read POST 🔑把一条通知标记为已读
/api/notifications/{notification_id} DELETE 🔑删除一条通知

图形验证码

URL HTTP 描述
/api/captchas POST 生成新的图形验证码

邮件

URL HTTP 描述
/api/emails POST 🔐发送邮件

图片

URL HTTP 描述
/api/images GET 🔐获取图片列表
/api/images POST 🔑上传图片
/api/images/{keys} DELETE 🔐批量删除图片
/api/images/{key} GET 获取指定图片信息
/api/images/{key} PATCH 🔐更新指定图片信息
/api/images/{key} DELETE 🔐删除指定图片

数据统计

URL HTTP 描述
/api/stats GET 🔐获取站点统计数据