Welcome to the Crowd REST API reference. This page documents the REST resources available in Crowd, along with expected HTTP response codes and sample requests. This set of REST APIs is intended to be used by applications connecting to Crowd.

The Crowd REST APIs allow you to address the Crowd data entities as 'resources'. This means that the data entities are identified by URIs and operated on by HTTP requests (GET, POST, PUT and DELETE). Below are details of the resources made available by the APIs. To use a REST API, your application will make an HTTP request and parse the response.

Depending on the resource, responses are returned as JSON and/or XML. For resources that offer both, you can use the Accept HTTP header to specify which one you prefer. URIs for Crowd's REST API resource have the following structure:

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

The following API names are available in Crowd:

• usermanagement - used by applications to interact with the Crowd server for user management operations
• admin - used for administrative operations on the Crowd server
• appmanagement - used for administrative operations on the Crowd server for application management

Each API has it's version. However, there is also a symbolic version, called latest, which resolves to the latest version supported by the given Crowd instance. As an example, if you wanted to retrieve information about a user 'admin' from a Crowd instance, you would access:

1
2
https://crowd-server:8095/crowd/rest/usermanagement/latest/user?username=admin

The preferred authentication methods for the Crowd REST APIs is HTTP basic authentication (when using SSL).

Please note that the usermanagement resource expects the callers to authenticate using the application credentials (i.e. the application name and password configured in Crowd). Calls to this APIs are restricted by IP as configured. Permissions and seen users, groups and other entities depend on the application configuration as well.

Other resources expect the callers to authenticate using the user credentials. Permissions depend on configured user permissions.

In order to simplify API responses, the Crowd REST API uses resource expansion. This means the API will only return parts of the resource when explicitly requested.

You can use the expand query parameter to specify a comma-separated list of entities that you want expanded, identifying each of them by name. For example, appending ?expand=attributes to a users's URI requests the inclusion of the user attribute names and values in the response. Continuing with our example above, we would use the following URL to get the attribute values for the 'admin' user:

1
2
https://crowd-server:8095/crowd/rest/usermanagement/latest/user?username=admin&expand=attributes

To discover the identifiers for each entity, look at the expand property in the parent object. In the JSON example below, the resource declares widgets as being expandable.

1
2
{
  "expand": "widgets",
  "widgets": {
    "widgets": []
  }
}

You can use the dot notation to specify expansion of entities within another entity. For example ?expand=widgets.fringels would expand the widgets collection and also the fringel property on each widget.

Crowd uses pagination to limit the response size for resources that return a potentially large collection of items. A request to a paged API will result in a values array, wrapped in a JSON object with some paging metadata:

1
2
{
  "values": [
    {
      /* result 0 */
    },
    {
      /* result 1 */
    },
    {
      /* result 2 */
    }
  ],
  "size": 3,
  "start": 0,
  "limit": 50,
  "isLastPage": true
}

Clients can use the limit and start query parameters to retrieve the desired number of results.

The limit parameter indicates how many results to return per page. Most APIs default to returning 50 if the limit is left unspecified. This number can be increased, but note that a resource-specific hard limit will apply. These hard limits can be configured by server administrators, so it's always best practice to check the limit attribute on the response to see what limit has been applied. The request to get a larger page should look like this:

1
2
http://host:port/context/rest/api-name/api-version/path/to/resource?limit={desired size of page}

The start parameter indicates which item should be used as the first item in the page of results. All paged responses contain an isLastPage attribute indicating whether another page of items exists.

The Crowd Query Language (CQL) allows developers using the Crowd REST API to perform user and group searches in a more intuitive and simpler form.

The Crowd REST API allows applications to POST to the Search resource with the search restriction in XML or JSON. The XML and JSON form is similar to the Java search restriction classes that Crowd uses.

In order to search for all users with an email of bob@example.net, you would previously POST to http://myhost.com:8095/rest/usermanagement/1/search?entity-type=user, with the following XML content:

1
2
<?xml version="1.0" encoding="UTF-8"?>
<property-search-restriction>
  <property>
    <name>email</name>
    <type>STRING</type>
  </property>
  <match-mode>EXACTLY_MATCHES</match-mode>
  <value>bob@example.net</value>
</property-search-restriction>

There is a much simpler way to perform user and group searches. You can now perform a GET request to the search resource with the restrictions expressed in CQL as a query parameter.

1
2
GET http://myhost.com:8095/rest/usermanagement/1/search?entity-type=ENTITY_TYPE&restriction=RESTRICTION

where ENTITY_TYPE is: user or group and RESTRICTION is the URL encoded search restriction expressed in CQL.

The above XML content now becomes:

1
2
email=bob@example.net

i.e.

1
2
GET http://myhost.com:8095/rest/usermanagement/1/search?entity-type=user&restriction=email%3Dbob%40example.net

Keywords Reference

AND

Used to combine multiple restrictions, allowing you to refine your search. The AND statement is satisfied if all of the conditions are true.

Note that you can use #parentheses to control the order in which statements are executed.

Examples

• Find all users with a first name of bob and an email of bob@example.net:

  1
  2
  firstName = "bob" and email = "bob@example.net"
  

• Find all inactive groups with a name starting with "admin":

  1
  2
  name = "admin*" and active = false
  

OR

Used to combine multiple restrictions, allowing you to expand your search. The OR statement is satisfied if any of the conditions are true.

Note that you can use #parentheses to control the order in which statements are executed.

Examples

• Find all users with either a last name of Smith or Jones:

  1
  2
  lastName = Smith or lastName = Jones
  

• Find all users created after December 2010 or a first name starting with Jo:

  1
  2
  createdDate > 2010-12 or firstName = Jo*
  

Property Names Reference

Crowd distinguishes between entity primary properties and entity secondary properties. The set of primary properties for each entity type is listed below with their type:

• User primary properties: name (String), email (String), firstName (String), lastName (String), displayName (String), active (Boolean), externalId (String), createdDate (Date), updatedDate (Date).
• Group primary properties: name (String), description (String), active (Boolean), local (Boolean), createdDate (Date), updatedDate (Date).

Custom attributes are secondary properties of type String and can be referred by their attribute key.

Operators Reference

EQUALS: =

The "=" operator is used to search for exact and partial matches of the specified value.

To find entities where the value of a specified field exactly matches multiple values, use multiple "=" statements with the #AND operator. Partial matches are performed with the wildcard, "*", symbol. The only currently supported partial matches are:

• starts-with ("term*") and
• contains ("*term*")

Examples

• Find all active users:

  1
  2
  active = true
  

• Find all users with a display name of John Smith:

  1
  2
  displayName = "John Smith"
  

• Find all users with a first name starting with Jo:

  1
  2
  firstName = "Jo*"
  

• Find all users with an email containing atlassian:

  1
  2
  email = "*atlassian*"
  

GREATER THAN: >

The ">" operator is used to search for entities where the value of the specified field is greater than the specified value. Cannot be used with #string fields.

Note that the ">" operator can only be used with fields which support ordering (e.g. date fields). To see a field's supported operators, check the individual #field reference.

Examples

• Find all groups created after 1 January 2010:

  1
  2
  createdDate > 2010-01-01
  

LESS THAN: <

The "<" operator is used to search for entities where the value of the specified field is less than the specified value. Cannot be used with #string fields.

Note that the "<" operator can only be used with fields which support ordering (e.g. date fields). To see a field's supported operators, check the individual #field reference.

Examples

• Find all groups created before the year 2011:

  1
  2
  updatedDate < 2011
  

Fields Reference

• User Fields
  • Email
  • Group Fields

User Fields

The following fields may be used in user queries.

Name

Search for users with the specified user name.

Note: this field supports partial-matching.

Syntax

1
2
name

Field Type

String

Supported Operators

Examples

• Find the user with username ernie:

  1
  2
  name = "ernie"
  

• Find all users with a username starting with ern:

  1
  2
  name = "ern*"
  

• Find all users with a username containing rni:

  1
  2
  name = *rni*
  

Email

Search for users with the specified email.

Note: this field supports partial-matching.

Syntax

1
2
email

Field Type

String

Supported Operators

Examples

• Find all users with an email of bob@example.net:

  1
  2
  email = "bob@example.net"
  

• Find all users with an email starting with bob:

  1
  2
  email = "bob*"
  

• Find all users with an email containing example:

  1
  2
  email = *example*
  

First Name

Search for users with the specified first name.

Note: this field supports partial-matching.

Syntax

1
2
firstName

Field Type

String

Supported Operators

Examples

• Find all users with a first name of Shrek:

  1
  2
  firstName = "Shrek"
  

• Find all users with a first name starting with Sh:

  1
  2
  firstName = "Sh*"
  

• Find all users with a first name containing hr:

  1
  2
  firstName = *hr*
  

Last Name

Search for users with the specified last name.

Note: this field supports partial-matching.

Syntax

1
2
lastName

Field Type

String

Supported Operators

Examples

• Find all users with a last name of Smith:

  1
  2
  lastName = "Smith"
  

• Find all users with a last name starting with Smi:

  1
  2
  lastName = "Smi*"
  

• Find all users with a last name containing mit:

  1
  2
  lastName = *mit*
  

Display Name

Search for users with the specified display name.

Note: this field supports partial-matching.

Syntax

1
2
displayName

Field Type

String

Supported Operators

Examples

• Find all users with a display name of John Smith:

  1
  2
  displayName = "John Smith"
  

• Find all users with a display name starting with John:

  1
  2
  displayName = "John*"
  

• Find all users with a display name containing Smi:

  1
  2
  displayName = *Smi*
  

Active

Search for users with the specified active field value. The only valid values for active are: true, false.

Syntax

1
2
active

Field Type

Boolean

Supported Operators

Examples

• Find all active users:

  1
  2
  active = true
  

• Find all inactive users:

  1
  2
  active = false
  

Created Date

Search for users created on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

• 2010-12-08T16:11:21.181+1100
• 2010-12-08T16:11:21.181
• 2010-12-08T16:11:21
• 2010-12-08T16:11
• 2010-12-08T16
• 2010-12-08
• 2010-12
• 2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

1
2
createdDate

Field Type

ISO-8601 Date

Supported Operators

Examples

• Find all users created exactly at 5:23pm on 15 December 2010:

  1
  2
  createdDate = 2010-12-15T17:23
  

• Find all users created before 2010:

  1
  2
  createdDate < 2010
  

• Find all users created after 15 December 2010 midnight:

  1
  2
  createdDate > 2010-12-15
  

Updated Date

Search for users updated on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

• 2010-12-08T16:11:21.181+1100
• 2010-12-08T16:11:21.181
• 2010-12-08T16:11:21
• 2010-12-08T16:11
• 2010-12-08T16
• 2010-12-08
• 2010-12
• 2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

1
2
updatedDate

Field Type

ISO-8601 Date

Supported Operators

Examples

• Find all users updated exactly at 5:23pm on 15 December 2010:

  1
  2
  updatedDate = 2010-12-15T17:23
  

• Find all users updated before 2010:

  1
  2
  updatedDate < 2010
  

• Find all users updated after 15 December 2010 midnight:

  1
  2
  updatedDate > 2010-12-15
  

Group Fields

The following fields may be used in group queries.

Name

Search for groups with the specified name.

Note: this field supports partial-matching.

Syntax

1
2
name

Field Type

String

Supported Operators

Examples

• Find the group with the name administrators:

  1
  2
  name = "administrators"
  

• Find all groups with a name starting with admin:

  1
  2
  name = "admin*"
  

• Find all groups with a name containing nistra:

  1
  2
  name = *nistra*
  

Active

Search for groups with the specified active field value. The only valid values for active are: true, false.

Syntax

1
2
active

Field Type

Boolean

Supported Operators

Examples

• Find all active groups:

  1
  2
  active = true
  

• Find all inactive groups:

  1
  2
  active = false
  

Created Date

Search for groups created on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

• 2010-12-08T16:11:21.181+1100
• 2010-12-08T16:11:21.181
• 2010-12-08T16:11:21
• 2010-12-08T16:11
• 2010-12-08T16
• 2010-12-08
• 2010-12
• 2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

1
2
createdDate

Field Type

ISO-8601 Date

Supported Operators

Examples

• Find all groups created exactly at 5:23pm on 15 December 2010:

  1
  2
  createdDate = 2010-12-15T17:23
  

• Find all groups created before 2010:

  1
  2
  createdDate < 2010
  

• Find all groups created after 15 December 2010 midnight:

  1
  2
  createdDate > 2010-12-15
  

Updated Date

Search for groups updated on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

• 2010-12-08T16:11:21.181+1100
• 2010-12-08T16:11:21.181
• 2010-12-08T16:11:21
• 2010-12-08T16:11
• 2010-12-08T16
• 2010-12-08
• 2010-12
• 2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

1
2
updatedDate

Field Type

ISO-8601 Date

Supported Operators

Examples

• Find all groups updated exactly at 5:23pm on 15 December 2010:

  1
  2
  updatedDate = 2010-12-15T17:23
  

• Find all groups updated before 2010:

  1
  2
  updatedDate < 2010
  

• Find all groups updated after 15 December 2010 midnight:

  1
  2
  updatedDate > 2010-12-15
  

Setting Precedence of Operators

You can use parentheses in complex CQL statements to enforce the precedence of #operators.

For example, if you want to find all users with a username of "bob", updated after January 2011, with either an email starting with "bob@ex" or the user was created before 1 January 2010, you can use parentheses to enforce the precedence of the boolean operators in your query, i.e.:

1
2
name="bob" AND (email = "bob@ex*" OR createdDate < 2010) AND updatedDate > 2011-01

Note that if you do not use parentheses, the operators have the following precedence starting from least to most:

1. OR
2. AND
3. =, <, >

Reserved Characters

CQL has a list of reserved characters:

• space (" ")
• "+"
• "."
• ","
• ";"
• "?"
• "|"
• "*"
• "/"
• "%"
• "^"
• "$"
• "#"
• "@"
• "["
• "]"
• "<"
• ">"

If you wish to use these characters in queries, you need to surround them with quote-marks (you can use either single quote-marks (') or double quote-marks (")).

For example:

1
2
firstName = "John Smith"

While some of these characters are not being used at the moment, it is highly recommended that none of the characters in the above list are used as they may be used in future releases of Crowd.

Reserved Words

CQL has a list of reserved words. These words need to be surrounded by quote-marks if you wish to use them in queries:

"and", "or", "<", ">"

While some of these words are not being used at the moment, it is highly recommended that none of the words in the above list are used unquoted, as they may be used in future releases of Crowd.