Using the Bamboo REST APIs

There are a number of characteristics that are common across the Bamboo REST APIs. These are described below.

REST Authentication

You can authenticate yourself for the REST APIs in two ways:

• Log into Bamboo manually. You will then be authenticated for the REST APIs for that same browser session.
• Use personal access token as a Bearer credential in an HTTP Authorisation header. For more information, see Personal access tokens.

Example

1
2
curl -H "Authorization: Bearer NDc4NDkyNDg3ODE3OstHYSeYC1UgXqRacSqvUbookcZk" http://localhost:8085/rest/api/latest/plan/PROJ-PLAN.json

• Use HTTP basic authentication (Deprecated) which contain Basic username:password at Authorisation HTTP header. The URL must also contain the os_authType=basic query parameter.

Example:

1
2
wget --http-user=admin --http-password=admin  http://localhost:8085/rest/api/latest/plan/PROJ-PLAN?os_authType=basic
curl --user admin:admin http://localhost:8085/rest/api/latest/plan/PROJ-PLAN?os_authType=basic

Or in a browser use:

1
2
http://host:8085/rest/api/latest/plan?os_authType=basic

REST Resources and URI Structure

URIs for a Bamboo REST API resource have the following structure:

1
2
http://host:port/rest/api-name/api-version/resource-name

Example:

1
2
http://myhost.com:8085/rest/api/latest/plan

The parts of the URI are:

• host and port define the host and port where the Bamboo application lives.
• rest denotes the REST API.
• api-name identifies a specific API. This will usually be api for the most of the Bamboo REST APIs.
• api-version is the API version number, e.g. latest, 1, 2, etc. See the section on API versions.
• resource-name identifies the required resource. In some cases, this may be a generic resource name such as /plan. In other cases, this may include a generic resource name and key. For example, /plan returns a list of the plan items and /foo/{plan-key} returns the full content of the plan identified by the given plan-key.

Refer to the details of the specific REST resources.

Media Types

The Bamboo REST APIs return HTTP responses in one of the following formats:

Example:

To request an HTTP response on JSON format:

1
2
http://myhost.com:8085/bamboo/rest/api/latest/plan.json

API Versions

The Bamboo REST APIs are version controlled. The version number of an API appears in its URI. For example, use this URI structure to request version 1 of the Bamboo REST API:

1
2
http://myhost.com:8085/bamboo/rest/api/1/

To get the latest version of the API, you can also use the latest key-word. For example, if versions 1 and 2 of the 'admin' API are available, the following two URIs will point to the same resources:

1
2
http://myhost.com:8085/bamboo/rest/api/latest/...
http://myhost.com:8085/bamboo/rest/api/2/...

Notes:

• The API version number is latest or an integer, such as 1 or 2.
• The API version is independent of the Bamboo release number.
• The API version may, or may not, change with a new Bamboo release. The API version number will change only when the updates to the API break the API contract, requiring changes in the code which uses the API. An addition to the API does not necessarily require a change to the API version number.

HTTP Response Codes

An error condition will return an HTTP error code as described in the Atlassian REST Guidelines.