構建完整的API構架與Buddy API使用Hello World示例

由 多青科技 發佈 2022-08-19T06:17:00.388133+00:00

本文將帶您了解常規API的構架以及HTTP語句與身份驗證權限默認情況下，每個工作區都啟用API。您可以在工作區設置中停用或啟用。 調用API方法的權限與網站服務中的權限相同。例如，如果刪除項目的權限僅限於管理員，則相同的限制將應用於API方法。

本文將帶您了解常規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"
}
關鍵字：
#code #程式開發

【amz嚴選】瞬間去污美妝清潔碗

售價 NT$ 290

【台灣製】陳時中同款_全面性防飛沫_全包覆式護目鏡

售價 NT$ 299-499

【amz嚴選】德國XINAI雙筒望遠鏡_高倍12x50

售價 NT$ 2,700

【amz嚴選】馬卡龍系列_不鏽鋼保溫保冰吸管杯_750ml

售價 NT$ 490

Nature Tree_肌膚停止鍵_黃金賦活神霜

售價 NT$ 990-1,280

【E‧Heart】秘密S輕塑褲

售價 NT$ 499

Relove_男性專用私密潔淨凝露

售價 NT$ 1,280

德國樂美思_專科PH5.5_凍齡霜_三倍升級版

售價 NT$ 999-1,980