本文将带您了解常规API的构架以及HTTP语句与身份验证
权限
默认情况下,每个工作区都启用API。您可以在工作区设置中停用或启用。 调用API方法的权限与网站服务中的权限相同。例如,如果删除项目的权限仅限于管理员,则相同的限制将应用于API方法。
端点
您可以在此处获取API:
https://api.buddy.works
您的Buddy自托管或本地部署API可在此处获得:
https://IP地址或域名/api
HTTP语句
对于每个操作,需要使用适当的HTTP语句:
语句 | 描述 |
---|---|
GET | 用于提取资源 |
POST | 用于创建资源 |
PATCH | 用于更新数据; 仅更新请求中发送的字段 |
PUT | 用于更新数据; 更新对象的所有属性; 如果不能发布内容,则设置为null |
DELETE | 用于删除资源 |
身份验证
使用OAuth2机制执行身份验证。
如果您已经拥有 access_token
,则使用 HTTP HEADER 发送请求:
Authorization: Bearer <access_token>
架构
所有请求都必须以JSON格式发送和接收。所有API请求都必须通过HTTPS执行。空字段作为 NULL
返回并且不会被省略。所有日期都以ISO格式返回:
yyyy-MM-dd'T'HH:mm:ssZ
摘要和详细对象
当您提取资源列表时,响应作为摘要返回,这意味着并非所有对象字段都返回。它以这种方式工作,以防止返回的大量数据对性能产生影响。例如,在获取提交列表时,响应以缩短的版本出现:
GET /workspaces/:domain/projects/:project_name/repository/commits
响应样本
HTTP
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
JSON
{
"url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits",
"html_url": "https://app.buddy.works/buddy/company-website/repository/commits",
"commits": [
{
"url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits/506a3963507943d6908154f4bc9646e829128a08",
"html_url": "https://app.buddy.works/buddy/company-website/repository/commit/506a3963507943d6908154f4bc9646e829128a08",
"revision": "506a3963507943d6908154f4bc9646e829128a08",
"author_date": "2016-01-19T12:36:33Z",
"commit_date": "2016-01-19T12:36:33Z",
"message": "init repo\n",
"committer": {
"url": "https://api.buddy.works/workspaces/buddy/member/1",
"html_url": "https://app.buddy.works/buddy/profile/1",
"id": 1,
"name": "Mike Benson",
"avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
},
"author": {
"url": "https://api.buddy.works/workspaces/buddy/member/1",
"html_url": "https://app.buddy.works/buddy/profile/1",
"id": 1,
"name": "Mike Benson",
"avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
}
}
]
}
当请求单个提交时,响应是一个完整的对象:
GET /workspaces/:domain/projects/:project_name/repository/commits/:revision
响应样本
HTTP
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
JSON
{
"url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/commits/506a3963507943d6908154f4bc9646e829128a08",
"html_url": "https://app.buddy.works/buddy/company-website/repository/commit/506a3963507943d6908154f4bc9646e829128a08",
"revision": "506a3963507943d6908154f4bc9646e829128a08",
"author_date": "2016-01-19T12:36:33Z",
"commit_date": "2016-01-19T12:36:33Z",
"message": "init repo\n",
"stats": {
"additions": 388,
"deletions": 0,
"total": 388
},
"files": [
{
"file_name": ".gitignore",
"status": "ADDED",
"additions": 3,
"deletions": 0,
"total": 3,
"patch": "@@ -0,0 +1,3 @@\n+.idea/\n+.DS_Store\n+css/\n"
}
],
"committer": {
"url": "https://api.buddy.works/workspaces/buddy/member/1",
"html_url": "https://app.buddy.works/buddy/profile/1",
"id": 1,
"name": "Mike Benson",
"avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
},
"author": {
"url": "https://api.buddy.works/workspaces/buddy/member/1",
"html_url": "https://app.buddy.works/buddy/profile/1",
"id": 1,
"name": "Mike Benson",
"avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png"
},
"content_url": "https://api.buddy.works/workspaces/buddy/projects/company-website/repository/contents?revision=506a3963507943d6908154f4bc9646e829128a08"
}
文件对象中的 status
可以是 ADDED
、MODIFIED
、REPLACED
或 DELETED
文档提供了每个API方法的示例响应。响应说明了该方法返回的所有属性。
参数
必需参数作为路径参数发送。例如,在获取提交列表时,项目的名称是必需的参数:
GET https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits
可选参数作为查询字符串发布。例如,为了将提交列表缩小到特定的时间范围,您需要执行以下方法:
GET https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits?since=2014-11-6T00:00:00Z&until=2014-11-7T00:00:00Z&page=1&per_page=2
对于 POST
、PATCH
、PUT
和 DELETE
,参数应作为JSON正文发送,Content-Type设置为 application/json
。例如,要添加一个项目,您需要执行以下请求:
请求
POST https://api.buddy.works/workspaces/buddy/projects
JSON
{
"name": "landing-page",
"display_name": "Landing page"
}
客户端出错
所有API请求都经过验证。如果出现问题,您将收到一个描述性错误,以便调用者可以快速修复。可以返回三种可能的客户端错误类型:
1. 如果您尝试在停用API的工作区中执行API方法
HTTP
HTTP/1.1 400 Bad Request
JSON
{
"errors": [
{
"message": "API is disabled in this workspace."
}
]
}
2. 如果URL格式错误
HTTP
HTTP/1.1 400 Bad Request
JSON
{
"errors": [
{
"message": "Invalid url: /api/ws/account/permissions"
}
]
}
3. 如果参数作为错误类型发送
HTTP
HTTP/1.1 400 Bad Request
JSON
{
"errors": [
{
"message": "Value of 'name' cannot be empty."
}
]
}
时区
一些请求可以使用时间戳进行参数化。例如,您可以使用查询参数“since/until”将提交列表限制在特定时间范围内。 所有日期都应以 UTC 时区发送。
速率限制
- 更新于2020年3月1日
用户可以每小时发出5000个任何资源类型请求。 如果您想查看当前的速率限制状态,请检查返回的任何API请求的HTTP标头:
GET https://api.buddy.works/user
HTTP
Status: 200 OK
X-Rate-Limit-Limit: 5000
X-Rate-Limit-Remaining: 4999
X-Rate-Limit-Reset: 1446629442
有关您当前速率限制状态的所有信息都通过标题告知:
表头名称 | 描述 |
---|---|
X-Rate-Limit-Limit | 客户在当前窗口中可以发出的当前请求数(60分钟) |
X-Rate-Limit-Remaining | 当前限速窗口中剩余的请求数 |
X-Rate-Limit-Reset | 当前速率限制窗口重置的时间(以UTC纪元秒为单位) |
如果超出限制,您将收到以下响应:
HTTP
HTTP/1.1 403 Forbidden
JSON
{
"errors": [
{
"message": "Rate limit exceeded."
}
]
}
分页
一些返回对象列表的请求默认分为20个项目的页面。要更改返回的项目数,您需要在查询参数中使用 per_page
。要获取后续页面,您需要使用 page
查询参数。如果没有找到参数page
,则只返回结果的第一页:
https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits?since=2014-11-6T00:00:00Z&until=2014-11-7T00:00:00Z&page=1&per_page=2
跨域资源共享
API支持来自任何来源的AJAX请求跨域资源共享(CORS)。这是从浏览器发送点击的示例请求 http://example.com
:
curl -kH "Origin: http://example.com" --verbose -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: X-Requested-With" -X OPTIONS https://api.buddy.works/workspaces/example/projects
OPTIONS /workspaces/example/projects HTTP/1.1
Host: api.buddy.works
User-Agent: curl/7.47.0
Accept: */*
Origin: http://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-Requested-With
HTTP/1.1 200 OK
Date: Thu, 20 Jul 2017 11:56:53 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: POST GET
X-Buddy-Media-Type: buddy.v1.0.0
Access-Control-Allow-Origin: *
Content-Length: 0
Server: Jetty(9.4.6.v20170531)
Hello World 示例
身份验证
在使用API之前,您需要进行身份验证。 身份验证基于oAuth机制。为了调用API方法,您需要一个访问令牌。Buddy允许您生成一个“个人访问令牌”,这使得上手更简易。您可以在您的帐户资料ID中获取。生成令牌时,您需要选择权限范围列表进行数据访问。
oAuth中描述了其他获取令牌的方法
首次检索API数据
调用API方法的最简单方法是cURL。打开终端并使用先前生成的令牌调用:
$curl https://api.buddy.works/user?access_token=732e9e20-50ba-4047-8a7b-c9b17259a2a2
或作为标头发送令牌
$ curl --header "Authorization: Bearer 732e9e20-50ba-4047-8a7b-c9b17259a2a2" https://api.buddy.works/user
这将以JSON格式接收有关您的帐户资料数据:
响应样本
HTTP
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
JSON
{
"url": "https://api.buddy.works/user",
"html_url": "https://app.buddy.works/my-id",
"id": 1,
"name": "Mike Benson",
"avatar_url": "https://app.buddy.works/image-server/user/0/0/0/0/0/0/1/d643744fbe5ebf2906a4d075a5b97110/w/32/32/AVATAR.png",
"workspaces_url": "https://api.buddy.works/workspaces"
}
JSON 复制 全屏