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

科技 08-17 来源： 多青科技

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

架构

所有请求都必须以JSON格式发送和接收。所有API请求都必须通过HTTPS执行。空字段作为 NULL 返回并且不会被省略。所有日期都以ISO格式返回：

yyyy-MM-dd'T'HH:mm:ssZ

摘要和详细对象

当您提取资源列表时，响应作为摘要返回，这意味着并非所有对象字段都返回。它以这种方式工作，以防止返回的大量数据对性能产生影响。例如，在获取提交列表时，响应以缩短的版本出现：

GET /workspaces/:domain/projects/:project_name/repository/commits

响应样本

HTTP

Status: 200 OKX-Rate-Limit-Limit: 1X-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
",      "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 OKX-Rate-Limit-Limit: 1X-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
",  "stats": {    "additions": 388,    "deletions": 0,    "total": 388  },  "files": [    {      "file_name": ".gitignore",      "status": "ADDED",      "additions": 3,      "deletions": 0,      "total": 3,      "patch": "@@ -0,0 +1,3 @@
+.idea/
+.DS_Store
+css/
"    }  ],  "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 OKX-Rate-Limit-Limit: 5000X-Rate-Limit-Remaining: 4999X-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.1Host: api.buddy.worksUser-Agent: curl/7.47.0Accept: */*Origin: http://example.comAccess-Control-Request-Method: POSTAccess-Control-Request-Headers: X-Requested-WithHTTP/1.1 200 OKDate: Thu, 20 Jul 2017 11:56:53 GMTAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Headers: Content-Type, AuthorizationAccess-Control-Allow-Methods: POST GETX-Buddy-Media-Type: buddy.v1.0.0Access-Control-Allow-Origin: *Content-Length: 0Server: 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 OKX-Rate-Limit-Limit: 1X-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"}
  • 支付宝打赏
  • 微信打赏
    • 构架   示例   完整
    发表评论
    留言与评论（共有 0 条评论） “”
       
    验证码：

    相关文章

    Java SE 9 多版本兼容 JAR 包示例
    Java SE 9 多版本兼容 JAR 包示例
    Django 4.x CSRF 站点保护示例和使用配置方法
    Django 4.x CSRF 站点保护示例和使
    小米 CEO 雷军 2022 年度演讲全文：穿越人生低谷的感悟的完整视频
    小米 CEO 雷军 2022 年度演讲全文：
    中石油编制！国内陆上油气行业又一重磅标准发布！
    中石油编制！国内陆上油气行业又一重
    「保姆级示例向」观察者模式
    「保姆级示例向」观察者模式
    java实现即时通信的完整步骤分享
    java实现即时通信的完整步骤分享

    推荐文章

    最热点击文章

    热门标签