Skip to content

Home

Jump to bottom
BB9z edited this page Jul 13, 2020 · 7 revisions

XXX 接口文档

目录

地址

🆙

格式与编码

如非特殊说明，请求的 HTTP body 需格式化为 json 格式，并标记 Content-Type 为 application/json。

服务器返回也是 json 的，并标记 Content-Type 为 application/json。

内容的编码方式均为 UTF-8（无 BOM）。

🆙

鉴权

接口请求时需要客户端在 HTTP header 中通过 Authorization 字段带上 token，格式为：

Authorization: token

声明无需权限验证的接口不需要带 token。

🆙

响应

请求成功时，响应 HTTP 状态码为 2xx，返回的内容包在 data 字段里，例如：

{
  "code": 0,
  "data": {
    "id": "TP4bl6sJQ-ndMYZHpAxuLTsSw-GcQRpVET0a69nA",
    "title": "Updated for Swift 5.3",
    "content": "Added information about multiple trailing closures to the Trailing Closures section.\nAdded information about synthesized implementations of Comparable for enumerations to the Adopting a Protocol Using a Synthesized Implementation section.",
    "author": {
      "id": "UAnOiIAvB1keXOBFfvUezgIQ",
      "name": "演示用户"
    },
    "create_time": "2020-06-22T10:00:00Z",
    "status": [],
    "allow_operations": ["comment", "edit"],
    "comment_count": 0,
    "like_count": 0
  }
}

请求失败，响应 HTTP 状态码为 4xx 或 5xx，返回的 code 非 0，并返回错误信息：

{
  "code": 1000,
  "error": "错误信息"
}

通用的错误码有：

  • 1003，token 无效，需要用户重新登入

🆙

响应：成功或失败

有些操作的 API 只需返回是否成功的结果，通过返回的 code 区分即可，0 成功，非 0 失败，这种情况错误是可选的。

分页请求

分页参数：

  • page，从 1 开始
  • page_size，分页大小，默认 10

注意：请求的分页参数需通过 URL 参数传递，不能在 body 中。

🆙

特殊数据的格式

日期

接口发送、接受的日期格式统一为 ISO 8601 格式，形如 2018-08-04T01:43:02Z。

🆙

ID 编号

对于整型 ID，App 中注意要使用长整型（64位或更高）解析、保存。

🆙

密码

强烈不建议明文传密码，如果确实需要，请删除这段及链接到此处的链接

前端发送密码时需要对字段内容进行特殊处理，处理方式为 sha512("原始内容"+"全局盐")。

注意：服务器接收到的用户密码虽然是处理过的非明文，但也不可直接存，应使用 bcrypt、scrypt 或更安全的算法进行处理保存

🆙

国际化

客户端通过 HTTP header 中的 Accept-Language 声明用户使用的语言，服务器根据该字段调整返回所用的语言。

举例

Accept-Language: en-US;q=1,zh-hans-US;q=0.9

🆙

Clone this wiki locally