Using the Crowd REST APIs

Available:

Crowd 2.1 and later.

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):

Query Parameter

Default Value

start-index

0

max-results

1000

Media Types

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

Response Format

Requested via...

JSON

Requested via one of the following:

  • application/json in the HTTP Accept header
  • .json extension

XML

Requested via one of the following:

  • application/xml in the HTTP Accept header
  • .xml extension

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

HTTP Response Code

Description

200 (OK)

Returned when an application request is successful.

401 (Unauthorized)

Returned when the application name/password is invalid or if the application does not exist. Invalid user authentication details do not result in this status code.

403 (Forbidden)

Returned when an application is not allowed to make the request, such as when the application is inactive or the client's IP address is not in the list of known application addresses.

404 (Not Found)

Returned when the requested resource does not exist. For example, the user does not exist, the group does not exist, or the group membership does not exist.

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>

Reason

Description

APPLICATION_ACCESS_DENIED

User does not have access to a particular application

APPLICATION_PERMISSION_DENIED

Application does not have permission to perform the operation

EXPIRED_CREDENTIAL

User credentials have expired

GROUP_NOT_FOUND

Group is not found

ILLEGAL_ARGUMENT

REST method is given an illegal argument

INACTIVE_ACCOUNT

User account is inactive

INVALID_USER_AUTHENTICATION

Username/password combination for authentication is invalid

INVALID_CREDENTIAL

The supplied credential is not valid. E.g. no password given when adding a user

INVALID_EMAIL

Given email address is not valid

INVALID_GROUP

Given group is invalid. E.g. unknown group type, adding a group that already exists

INVALID_SSO_TOKEN

Given SSO token is invalid

INVALID_USER

Given user is invalid. E.g. adding a user that already exists

MEMBERSHIP_NOT_FOUND

When the child-parent relationship does not exist

NESTED_GROUPS_NOT_SUPPORTED

Nested groups are not supported

UNSUPPORTED_OPERATION

Requested operation is not supported

USER_NOT_FOUND

User not found

OPERATION_FAILED

Operation failed for any other reason

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.

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

Rate this page: