Using the Crowd REST APIs

Crowd offers a set of REST APIs for use by applications connecting to Crowd.

Please note the main difference between Crowd APIs and the APIs of other applications like JIRA and Confluence: In Crowd, an application is the client of Crowd, whereas in JIRA/Confluence a user is the client. For example, when authenticating a request to a Crowd REST resource via basic authentication, the application name and password is used (and not a username and password). Keep this in mind when using the REST APIs.

This page contains information on the factors common across all or most of the Crowd REST APIs. You can also read 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

API Name - usermanagement

In Crowd 2.1, the only api-name available is usermanagement. This is the API that allows an application to interact with the Crowd server.

Examples

With context:

1
2
http://myhost.com:8095/crowd/rest/usermanagement/1/user?username=USERNAME
http://localhost:8095/crowd/rest/usermanagement/latest/user?username=USERNAME

Or without context:

1
2
http://crowd.myhost.com:8095/rest/usermanagement/1/user?username=USERNAME
http://crowd.myhost.com:8095/rest/usermanagement/latest/user?username=USERNAME

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. In Crowd, the usermanagement API allows applications to interact with Crowd. (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.

URL Encoding

Query parameters will be the percent encoded representation of the UTF-8 bytes comprising the string.

Optional start-index and max-results Query Parameters

If a resource method offers an optional start-index and max-results query parameters, the default values are as follows (if not specified):

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 'usermanagement' API:

1
2
http://host:port/context/rest/usermanagement/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 'usermanagement' API are available, the following two URIs will point to the same resources:

• 1
  2
  http://host:port/context/rest/usermanagement/latest/...
  

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

Your environment must retain cookies set by the Crowd server and retransmit them on subsequent calls, otherwise Crowd will have to re-authenticate the application on every REST call.

HTTP Response Codes and Error Responses

All error responses except for 401 (Unauthorized) and 403 (Forbidden) return the following entity:

Unsuccessful Response

1
2
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <reason>...</reason>
  <message>Error message</message>
</error>

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

Crowd REST Resources
Overview of the Crowd REST APIs
Crowd Developer Documentation