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 HTTP basic authentication (Authorisation HTTP header) containing ‘Basic username:password’. The URL must also contain the ‘os_authType=basic’ query parameter.

Example:

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

Or in a browser use:

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:

http://host:port/bamboo/rest/api-name/api-version/resource-name

Example:

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

The parts of the URI are:

• host and port define the host and port where the Bamboo application lives.
• bamboo signifies that the request is to be directed to the ‘bamboo’ application.
• rest denotes the REST API.
• api-name identifies a specific API. This will always be api for a Bamboo REST API.
• api-version is the API version number, e.g. latest, 1, 2, etc. See the section on BAMBOO:API version control.
• resource-name identifies the required resource. In some cases, this may be a generic resource name such as /foo. In other cases, this may include a generic resource name and key. For example, /foo returns a list of the foo items and /foo/{key} returns the full content of the foo identified by the given 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:

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:

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:

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

Notes:

• The API version number is 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.

Methods

You will use the standard HTTP methods to access Bamboo via the REST APIs. Please refer to the resource descriptions for further details.