MDClub API 文档

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

接口文档说明

  • 接口描述中,若含 🔑 图标,表示该接口需要登录后才能调用。
  • 接口描述中,若含 🔐 图标,表示该接口需要登录、且仅管理员有权限调用。
  • 接口返回值的字段描述中,若含 🔐 图标,表示只有管理员调用接口时,返回值中才会包含该字段。
  • 接口参数的描述中,若含 🔐 图标,表示只有管理员才能添加该参数。

GETPUTDELETE 请求均符合幂等性。

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

使用详解

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

  • 开发各种主题的前端页面。
  • 开发 Android、iOS、Windows 等客户端应用。
  • 在其他项目中,获取 MDClub 中的数据。

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系统维护中
100002IP 请求超过上限
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指定通知不存在

接口列表

身份验证

URLHTTP描述
/api/tokensPOST生成 Token

系统设置

URLHTTP描述
/api/optionsGET获取站点全局设置参数
/api/optionsPATCH🔐更新站点全局设置

用户

URLHTTP描述
/api/user/answersGET🔑获取当前登录用户发表的回答
/api/user/articlesGET🔑获取当前登录用户发表的文章
/api/user/avatarPOST🔑上传当前登录用户的头像
/api/user/avatarDELETE🔑删除当前登录用户的头像,并重置为默认头像
/api/user/commentsGET🔑获取当前登录用户发表的评论
/api/user/coverPOST🔑上传当前登录用户的封面
/api/user/coverDELETE🔑删除当前登录用户的封面,并重置为默认封面
/api/user/followeesGET🔑获取当前登录用户关注的用户
/api/user/followersGET🔑获取当前登录用户的关注者
/api/user/following_articlesGET🔑获取登录用户关注的文章
/api/user/following_questionsGET🔑获取登录用户关注的提问
/api/user/following_topicsGET🔑获取登录用户关注的话题
/api/user/password/emailPOST发送重置密码邮箱验证码
/api/user/passwordPUT验证邮箱并更新密码
/api/user/questionsGET🔑获取登录用户发表的提问
/api/user/register/emailPOST发送注册邮箱验证码
/api/userGET🔑获取当前登录用户的信息
/api/userPATCH🔑更新当前登录用户信息
/api/usersGET获取用户列表
/api/usersPOST验证邮箱并创建账号
/api/users/{user_ids}/disablePOST🔐批量禁用用户
/api/users/{user_ids}/enablePOST🔐批量恢复用户
/api/users/{user_id}/answersGET获取指定用户发表的回答
/api/users/{user_id}/articlesGET获取指定用户发表的文章
/api/users/{user_id}/avatarDELETE🔐删除指定用户的头像,并重置为默认头像
/api/users/{user_id}/commentsGET获取指定用户发表的评论
/api/users/{user_id}/coverDELETE🔐删除指定用户的封面,并重置为默认封面
/api/users/{user_id}/disablePOST🔐禁用指定用户
/api/users/{user_id}/enablePOST🔐恢复指定用户
/api/users/{user_id}/followeesGET获取指定用户关注的用户列表
/api/users/{user_id}/followersGET获取指定用户的关注者
/api/users/{user_id}/followersPOST🔑添加关注
/api/users/{user_id}/followersDELETE🔑取消关注
/api/users/{user_id}/following_articlesGET获取指定用户关注的文章列表
/api/users/{user_id}/following_questionsGET获取指定用户关注的提问列表
/api/users/{user_id}/following_topicsGET获取指定用户关注的话题列表
/api/users/{user_id}/questionsGET获取指定用户发表的提问
/api/users/{user_id}GET获取指定用户信息
/api/users/{user_id}PATCH🔐更新指定用户信息

话题

URLHTTP描述
/api/topicsGET获取全部话题
/api/topicsPOST🔐发布话题
/api/topics/{topic_ids}/trashPOST🔐批量把话题放入回收站
/api/topics/{topic_ids}/untrashPOST🔐批量把话题移出回收站
/api/topics/{topic_ids}DELETE🔐批量删除话题
/api/topics/{topic_id}/articlesGET获取指定话题下的文章
/api/topics/{topic_id}/followersGET获取指定话题的关注者
/api/topics/{topic_id}/followersPOST🔑关注指定话题
/api/topics/{topic_id}/followersDELETE🔑取消关注指定话题
/api/topics/{topic_id}/questionsGET获取指定话题下的提问
/api/topics/{topic_id}/trashPOST🔐把话题放入回收站
/api/topics/{topic_id}/untrashPOST🔐把话题移出回收站
/api/topics/{topic_id}GET获取指定话题信息
/api/topics/{topic_id}POST🔐更新话题信息
/api/topics/{topic_id}DELETE🔐删除话题

提问

URLHTTP描述
/api/questionsGET获取提问列表
/api/questionsPOST🔑发表提问
/api/questions/{question_ids}/trashPOST🔐批量把提问放入回收站
/api/questions/{question_ids}/untrashPOST🔐批量把提问移出回收站
/api/questions/{question_ids}DELETE🔐批量删除提问
/api/questions/{question_id}/answersGET获取指定提问下的回答
/api/questions/{question_id}/answersPOST🔑在指定提问下发表回答
/api/questions/{question_id}/commentsGET获取指定提问的评论
/api/questions/{question_id}/commentsPOST🔑在指定提问下发表评论
/api/questions/{question_id}/followersGET获取指定提问的关注者
/api/questions/{question_id}/followersPOST🔑添加关注
/api/questions/{question_id}/followersDELETE🔑取消关注
/api/questions/{question_id}/trashPOST🔐把提问放入回收站
/api/questions/{question_id}/untrashPOST🔐把提问移出回收站
/api/questions/{question_id}/votersGET获取提问的投票者
/api/questions/{question_id}/votersPOST🔑为提问投票
/api/questions/{question_id}/votersDELETE🔑取消为提问的投票
/api/questions/{question_id}GET获取指定提问信息
/api/questions/{question_id}PATCH🔑更新提问信息
/api/questions/{question_id}DELETE🔑删除提问

回答

URLHTTP描述
/api/answersGET🔐获取回答列表
/api/answers/{answer_ids}/trashPOST🔐批量把回答放入回收站
/api/answers/{answer_ids}/untrashPOST🔐批量把回答移出回收站
/api/answers/{answer_ids}DELETE🔐批量删除回答
/api/answers/{answer_id}/commentsGET获取指定回答的评论
/api/answers/{answer_id}/commentsPOST在指定回答下发表评论
/api/answers/{answer_id}/trashPOST🔐把回答放入回收站
/api/answers/{answer_id}/untrashPOST🔐把回答移出回收站
/api/answers/{answer_id}/votersGET获取回答的投票者
/api/answers/{answer_id}/votersPOST🔑为回答投票
/api/answers/{answer_id}/votersDELETE🔑取消为回答的投票
/api/answers/{answer_id}GET获取回答详情
/api/answers/{answer_id}PATCH🔑修改回答信息
/api/answers/{answer_id}DELETE🔑删除回答

文章

URLHTTP描述
/api/articlesGET获取文章列表
/api/articlesPOST🔑发表文章
/api/articles/{article_ids}/trashPOST🔐批量把文章放入回收站
/api/articles/{article_ids}/untrashPOST🔐批量把文章移出回收站
/api/articles/{article_ids}DELETE🔐批量删除文章
/api/articles/{article_id}/commentsGET获取指定文章的评论列表
/api/articles/{article_id}/commentsPOST🔑在指定文章下发表评论
/api/articles/{article_id}/followersGET获取指定文章的关注者
/api/articles/{article_id}/followersPOST🔑添加关注
/api/articles/{article_id}/followersDELETE🔑取消关注
/api/articles/{article_id}/trashPOST🔐把文章放入回收站
/api/articles/{article_id}/untrashPOST🔐把文章移出回收站
/api/articles/{article_id}/votersGET获取文章的投票者
/api/articles/{article_id}/votersPOST🔑为文章投票
/api/articles/{article_id}/votersDELETE🔑取消为文章的投票
/api/articles/{article_id}GET获取指定文章信息
/api/articles/{article_id}PATCH🔑更新文章信息
/api/articles/{article_id}DELETE🔑删除文章

评论

URLHTTP描述
/api/commentsGET🔐获取所有评论
/api/comments/{comment_ids}/trashPOST🔐批量把评论放入回收站
/api/comments/{comment_ids}/untrashPOST🔐批量把评论移出回收站
/api/comments/{comment_ids}DELETE🔐批量删除评论
/api/comments/{comment_id}/repliesGET获取指定评论的回复
/api/comments/{comment_id}/repliesPOST🔑在指定评论下发表回复
/api/comments/{comment_id}/trashPOST🔐把评论放入回收站
/api/comments/{comment_id}/untrashPOST🔐把评论移出回收站
/api/comments/{comment_id}/votersGET获取评论的投票者
/api/comments/{comment_id}/votersPOST🔑为评论投票
/api/comments/{comment_id}/votersDELETE🔑取消为评论的投票
/api/comments/{comment_id}GET获取评论详情
/api/comments/{comment_id}PATCH🔑修改评论
/api/comments/{comment_id}DELETE🔑删除评论

举报

URLHTTP描述
/api/reportsGET🔐获取被举报的内容列表
/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🔐删除举报

私信

URLHTTP描述

通知

URLHTTP描述
/api/notifications/countGET🔑获取未读通知数量
/api/notifications/readPOST🔑把所有通知标记为已读
/api/notificationsGET🔑获取通知列表
/api/notificationsDELETE🔑删除所有通知
/api/notifications/{notification_ids}/readPOST🔑批量把通知标记为已读
/api/notifications/{notification_ids}DELETE🔑批量删除通知
/api/notifications/{notification_id}/readPOST🔑把一条通知标记为已读
/api/notifications/{notification_id}DELETE🔑删除一条通知

图形验证码

URLHTTP描述
/api/captchasPOST生成新的图形验证码

邮件

URLHTTP描述
/api/emailsPOST🔐发送邮件

图片

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

数据统计

URLHTTP描述
/api/statsGET🔐获取站点统计数据