Overview
Here you’ll find basic information on the Buddy’s API. If you’d like to see how things work in action, go to Hello World. In case of questions or requests, reach out on the live chat or write to support@buddy.works.
Permissions
By default, the API is enabled in every workspace. You can disable it in the workspace settings. Permissions for calling out the API methods are the same as those in the website service. For example, if the ability to delete projects is restricted to admins only, the same restriction will be applied to the API methods.
Endpoint
Depending on the account type, the API is available from three locations.
For US accounts starting with app.buddy.works
:
https://api.buddy.works
For EU accounts starting with eu.buddy.works
:
https://api.eu.buddy.works
For self-hosted installations of Buddy:
https://YOUR-IP-ADDRESS/api
HTTP Verbs
For each action, appropriate HTTP verbs need to be used:
Verb | Description |
---|---|
GET | used to fetch resources |
POST | used to create resources |
PATCH | used to update data; only fields sent in the request are updated |
PUT | used to update data; updates all properties of the object; set to null if something is not to be posted |
DELETE | used to delete resources |
Authentication
Authentication is performed with OAuth2 mechanisms.
If you already have access_token
, requests are sent with an HTTP HEADER:
Authorization: Bearer <access_token>
Schema
All requests must be sent and are received in JSON format. All API requests must be executed over HTTPS. Empty fields are returned as NULL
and are not omitted. All dates are returned in the ISO format:
yyyy-MM-dd'T'HH:mm:ssZ
Summary and Detailed Objects
When you fetch a list of resources, the response is returned as a summary, which means that not all object fields are returned. It works this way to prevent impact on performance by large amount of data returned. For example, when fetching a list of commits, the response comes in a shortened version:
GET /workspaces/:domain/projects/:project_name/repository/commits
Sample Response
HTTP
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
JSON
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" } } ] }
When asking for a single commit, however, the response is a full object:
GET /workspaces/:domain/projects/:project_name/repository/commits/:revision
Sample Response
HTTP
Status: 200 OK
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 999
JSON
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
in file object can be either ADDED
, MODIFIED
, REPLACED
, or DELETED
The documentation provides example responses for each API method. The response illustrates all attributes that are returned by that method.
Parameters
Required parameters are sent as path parameters. For example, the name of the project is a required parameter when fetching a list of commits:
GET https://api.buddy.works/workspaces/:domain/projects/:project_name/repository/commits
Optional parameters are posted as a query string. For example, in order to narrow a commit list to a specific time range, you need to execute the following method:
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
For POST
, PATCH
, PUT
and DELETE
, parameters should be sent as body in JSON with Content-Type set to application/json
. For example, to add a project you need to execute the following request:
Request
POST https://api.buddy.works/workspaces/buddy/projects
JSON
json{ "name": "landing-page", "display_name": "Landing page" }
Client Errors
All API requests are validated. If something goes wrong, you’ll receive a descriptive error so that it can be quickly fixed by the invoker. There are three possible types of client errors that can be returned:
1. If you’re trying to execute an API method in a workspace with disabled API
HTTP
HTTP/1.1 400 Bad Request
JSON
json{ "errors": [ { "message": "API is disabled in this workspace." } ] }
2. If the URL is in bad format
HTTP
HTTP/1.1 400 Bad Request
JSON
json{ "errors": [ { "message": "Invalid url: /api/ws/account/permissions" } ] }
3. If the parameters are sent as a wrong type
HTTP
HTTP/1.1 400 Bad Request
JSON
json{ "errors": [ { "message": "Value of 'name' cannot be empty." } ] }
Timezone
Some requests can be paremetrized with a timestamp. For example, you can restrict a list of commits to a specific time range with the query param since/until
. All dates should be sent in UTC timezone.
Rate Limiting
User is allowed to make 5000 requests per hour regardless of the resource type. If you want to see your current rate limit status, check the returned HTTP headers of any API request:
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
All information about your current rate limit status is told with headers:
Header Name | Description |
---|---|
X-Rate-Limit-Limit | The current number of requests that the consumer can make in the current window (60 minutes). |
X-Rate-Limit-Remaining | The number of requests remaining in the current rate limit window. |
X-Rate-Limit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |
If the limit is exceeded, you’ll receive the following response:
HTTP
HTTP/1.1 403 Forbidden
JSON
json{ "errors": [ { "message": "Rate limit exceeded." } ] }
Pagination
Some requests which return a list of objects are divided in pages of 20 items as default. To change the number of items returned, you need to use per_page
in the query parameter. To fetch the proceeding pages, you need to use the page
query parameter. If the parameter page
is not found, only the first page of the results will be returned:
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
Cross Origin Resource Sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. Here’s a sample request sent from a browser hitting 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)
Last modified on Sep 23, 2024