Deprecated - Crowd Admin REST APIs

This page contains information on the factors common across all or most of the Crowd REST APIs. Another page contains the details of the specific REST resources.

REST Resources and URI Structure

URIs for a Crowd 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

**Examples:** With context:

1
2
http://myhost.com:8095/crowd/rest/admin/1/directory
http://localhost:8095/crowd/rest/admin/latest/directory

Or without context:

1
2
http://crowd.myhost.com:8095/rest/admin/1/directory
http://crowd.myhost.com:8095/rest/admin/latest/directory

Here is an explanation for each part of the URI:

• host and port define the host and port where the Crowd application lives.
• context is the servlet context of the Crowd installation. For example, the context might be crowd. Omit this section if your URI does not include a context.
• rest denotes the REST API.
• api-name identifies a specific Crowd API. For example, admin is the API that allows interaction with the Crowd 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 CROWD: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 Crowd REST APIs return HTTP responses in one of the following formats:

API Versions

The Crowd 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/admin/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/admin/latest/...
  

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

Notes:

• The API version number is an integer, such as 1 or 2.
• The API version is independent of the Crowd release number.
• The API version may, or may not, change with a new Crowd 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 Crowd will support at least two API versions i.e. the latest API version and the previous API version.

Authentication

Access to all resources (using any method) requires the client to be authenticated, via basic authentication. See RFC 2617.

For example, the following cURL request searches for a user called 'smith', with basic authentication where the username and password are both 'admin':

1
2
curl http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user?search=smith -u admin:admin

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 Crowd via the REST APIs. Please refer to the resource descriptions to see the HTTP methods available for each resource.

RELATED TOPICS

Deprecated - Crowd Admin REST Resources
Overview of the Crowd REST APIs
Crowd Developer Documentation