基本路径


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


HTTP Verbs

Verb

Description

GET

用于获取数据

POST

用于创建数据

PUT

用于修改部分数据,例如一个文档标题,正文

DELETE

用于删除数据

HTTP 提交数据说明

当 POSTPUT 请求的时候,请确保 Request Content-Type 是 application/json 类型。


req.Headers.Add("Content-Type", "application/json")



User-Agent Header

为了确保我们能知道访问者是谁,API 要求必须传递 User-Agent Header,否则将会拒绝请求。


例如:

req.Headers.Add("User-Agent", "这里可以填应用名称")


用户认证

语雀 API 目前使用 Token 机制来实现用户认证。


你需要在请求的 HTTP Headers 传入 X-Auth-Token 带入用户的 Token 信息,用于认证。


获取 Token 可通过点击语雀的个人头像,并进入 个人设置 页面拿到,如下图:

image.png


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 标准格式,请按照标准方式进行转换。