本文将带您了解常规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/projectsOPTIONS /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-WithHTTP/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 复制全屏

构建完整的API构架与Buddy API使用示例相关推荐

基于 Node.js + Koa 构建完整的 Web API （配置 ESLint 和使用 Airbnb 编码规范）
主题内容:基于 Node.js + Koa 构建完整的 Web API (配置 ESLint 和使用 Airbnb 代码规范) 背景描述:上一篇基于 Node.js + Koa 构建完整的 Web ...
如何基于 Notadd 构建 API （Laravel 写 API）
如何基于 Notadd 构建 API Notadd 底层实现了 passport 机制,有统一的授权管理,主要支持两种方式进行 API 授权,一个是 client,领一个是 passport,这个在其 ...
Vue2+VueRouter2+webpack 构建项目实战（四）接通api，先渲染个列表
Vue2+VueRouter2+webpack 构建项目实战(四)接通api,先渲染个列表: Vue2+VueRouter2+Webpack+Axios 构建项目实战2017重制版(一)基础知识概述 ...
ROS探索总结（十六）（十七）（十八）（十九）——HRMRP机器人的设计构建完整的机器人应用系统重读tf 如何配置机器人的导航功能
ROS探索总结(十六)--HRMRP机器人的设计 1. HRMRP简介 HRMRP(Hybrid Real-time Mobile Robot Platform,混合实时移动机器人平台 ...
构建服务器_如何使用无服务器构建完整的后端系统
构建服务器 This article will teach you how to build and deploy everything you need to be able to build a ...
如何使用Node.js构建完整的GraphQL服务器
by Jack R. Scott 杰克·R·斯科特(Jack R.Scott) 如何使用Node.js构建完整的GraphQL服务器 (How to build a full GraphQL serv ...
python api测试框架_python api 测试框架
python常用框架 Django: Python Web应用开发框架 Django 应该是最出名的Python框架,GAE甚至Erlang都有框架受它影响.Django是走大而全的方向,它最出名的是 ...
【小程序云开发】不用后端也能构建完整的微信小程序
文章目录什么是微信小程序云函数云数据库 HTTP 云函数定时触发云函数总结写在最后什么是微信小程序云函数微信小程序云函数是通过微信小程序云开发提供的一种服务器端代码,用于在小程序中进行服 ...
如何更好的设计RESTful API（创建公开API）
https://zhuanlan.zhihu.com/p/24592119?utm_source=tuicool&utm_medium=referral 作者:知秋z 链接:https://z ...

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

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

权限

端点

HTTP语句

身份验证

架构

参数

客户端出错

时区

速率限制

分页

跨域资源共享

Hello World 示例

身份验证

首次检索API数据

构建完整的API构架与Buddy API使用示例相关推荐

最新文章

热门文章