基本路径

如果是获取企业空间下的数据,请用企业的二级域名,例如:https://tmall.yuque.com/api/v2/

HTTP Verbs

Verb
Description
GET
用于获取数据
POST
用于创建数据
PUT
用于修改部分数据,例如一个文档标题,正文
DELETE
用于删除数据

HTTP 提交数据说明

当 POSTPUT 请求的时候,请确保 Request Content-Type 是 application/x-www-form-urlencoded类型。
req.Headers.Add("Content-Type", "application/x-www-form-urlencoded")

User-Agent Header

为了确保我们能知道访问者是谁,API 要求必须传递 User-Agent Header,否则将会拒绝请求。
例如:
req.Headers.Add("User-Agent", "my-app-name")

用户认证

语雀 API 目前使用 Token 机制来实现用户认证。
你需要在请求的 HTTP Headers 传入 X-Auth-Token 带入用户的 Token 信息,用于认证。
获取 Token 可通过点击语雀的个人头像,并进入 个人设置 页面拿到。
TIP💡: 别忘了,假如需要获取的数据是“公开”的,那是不需要用户认证的哦!
For example
curl -H "X-Auth-Token: gCmkIlgAtuc3vFwpLfeM1w==" https://www.yuque.com/api/v2/hello
Response
{
  "data":{
    "message":"Hello 小明"
  }
}
X-Auth-Token 依据用户有的权限,决定了能获取到的数据,例如,假如 “小明” 这个账号是 “语雀/帮助” 这个文档仓库的 Owner,那么通过他的 Token 可以获取到这个仓库的所有信息。
其他情况由具体的功能权限设定来决定能获取到什么样的数据,以及那些数据有修改权限,详见后面 API 的具体接口返回的 abilities 描述。

HTTP 状态码

参数说明

Name
Description
Example
id
数据的唯一编号/主键
1984
login
用户/团队的唯一名称
用户/团队编号
用户:用户个人路径
团队:如语雀团队,login 值为 yuque
book_slug
仓库唯一名称
语雀开发者文档这个仓库,book_slug 值为 developer
namespace
仓库的唯一名称
需要组合 :login/:book_slug
或可以直接使用仓库编号
yuque/developer
slug
文档唯一名称
当前这篇文档的 slug 值为 api

返回数据格式

{
  "data": {
    "id": 10,
    "slug": "weekly",
    "name": "技术周刊",
    "abilities": {
      "update": false,
      "destroy": false
    }
  },
  "meta": {
    "liked": false,
    "followed": false,
  }
}

Rate Limit 访问频率限制

每次请求 Response Header 将会返回频率限制的信息,例如:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
如果超过限制,将会返回:
HTTP/1.1 429 Too Many Requests

DateTime 格式

DateTime 使用 ISO 8601 标准格式,请按照标准方式进行转换。