本文将带您了解常规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"
}

首次从API更新数据

要更新您的帐户资料，您只需发送一个带有要编辑变量的PATCH：

$ curl -request PATCH --data "{\"title\": \"Buddy is awesome! He's my friend and shit\"}" https://api.buddy.works/user

构建完整的API构架与Buddy API使用示例

本文将带您了解常规API的构架以及HTTP语句与身份验证

权限

端点

HTTP语句

身份验证

架构

参数

客户端出错

时区

速率限制

分页

跨域资源共享

Hello World 示例

身份验证

首次检索API数据

首次从API更新数据