Using the REST APIs - prototype only

REST Authentication

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

• Log in to Confluence manually. You will then be authenticated for the REST APIs for that same browser session.
• Use HTTP basic authentication (Authorization HTTP header) containing 'Basic username:password'. Please note however, username:password must be base64 encoded. The URL must also contain the 'os_authType=basic' query parameter.

REST Resources and URI Structure

URIs for a Confluence REST API resource have the following structure:
With context:

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

Or without context:

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

NOTE: In Confluence 3.1 and Confluence 3.2, the only available api-name is prototype.

Examples:
With context:

1
2
http://myhost.com:8080/confluence/rest/prototype/1/space/ds
http://localhost:8080/confluence/rest/prototype/latest/space/ds

Or without context:

1
2
http://confluence.myhost.com:8095/rest/prototype/1/space/ds
http://confluence.myhost.com:8095/rest/prototype/latest/space/ds

Here is an explanation for each part of the URI:

• host and port define the host and port where the Confluence application lives.
• context is the servlet context of the Confluence installation. For example, the context might be confluence. Omit this section if your URI does not include a context.
• rest denotes the REST API.
• api-name identifies a specific Confluence API. For example, admin is the API that allows interaction with the Confluence Administration Console. (This is the path declared in the REST module type in the REST plugin descriptor.)
• api-version is the API version number, e.g. 1 or 2. See the section on 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.

Media Types

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

API Versions

The Confluence REST APIs are subject to version control. The version number of an API appears in its URI. For example, use this URI structure to request version 1 of the 'admin' API:

1
2
http://host:port/context/rest/prototype/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://host:port/context/rest/prototype/latest/...
  

• 1
  2
  http://host:port/context/rest/prototype/2/...
  

Notes:

• The API version number is an integer, such as 1 or 2.
• The API version is independent of the Confluence release number.
• The API version may, or may not, change with a new Confluence 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.
• In the future, when there are multiple API versions available, it is the intention that each version of Confluence will support at least two API versions i.e. the latest API version and the previous API version.

HTTP Response Codes

An error condition will return an HTTP error code as described in the Atlassian REST API design guidelines version 1.

Methods

You will use the standard HTTP methods to access Confluence via the REST APIs.