MDClub 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 使用了 GET、POST、PUT、PATCH、DELETE 请求方式，然而部分老旧的浏览器、或者部分小程序平台不支持其中部分请求方式。MDClub 支持通过 X-HTTP-Method-Override 重写请求方式。

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

错误代码

接口列表

身份验证

系统设置

用户

话题

提问

回答

文章

评论

举报

私信

通知

图形验证码

邮件

图片

数据统计