This page last changed on Jul 29, 2009 by smaddox.

The Crowd REST APIs allow you to address the Crowd data entities as 'resources'. This means that they are identified by URIs and operated on by HTTP requests, chiefly GET and POST. Whenever you GET one of these resources, you receive a representation encoded using XML or JSON. Below are details of the resources made available by the APIs.

Experimental APIs
Crowd's REST APIs are experimental at this stage. We will be adding to them in future releases. So please expect some API changes We will be delighted if you use the APIs and give us your feedback via our JIRA project.

On this page:

Introduction

URI Structure

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

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

Or without context:

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

In Crowd 2.0, the only api-name available is admin, This is the API that allows interaction with the Crowd Administration Console.

Examples:
With context:

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

Or without context:

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

More...

Please refer to the Crowd REST API usage guide for a description of the common factors in the APIs, including a full explanation of the URI format, authentication, API versions, etc.

Directory List

URI /directory
Description Lists all the directories managed by the Crowd server.
URI Parameters None.
The directory resource does not currently support the search parameter. There is an existing improvement request: CWD-1603.
HTTP Methods
  • GET — Returns a list of directories.

Example of a GET request:

http://localhost:8095/crowd/rest/admin/latest/directory/

Example of XML response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<directories>
 <directory>
  <name>Active Directory</name> 
  <type>CONNECTOR</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.connector.MicrosoftActiveDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Atlassian Crowd</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Crowd Internal</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Delegated Auth Directory</name> 
  <type>DELEGATING</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.delegated.DelegatedAuthenticationDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Employees</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
  </directory>
 <directory>
  <name>My Own Connector</name> 
  <type>CUSTOM</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.custom.MyOwnConnector</implementationClass> 
  </directory>
</directories>

Elements in the response:

Element Description Attributes
directories A list of directories defined in Crowd.  
  Refer to the section on directory information below for the elements describing each directory.  

Example of JSON response:

{"directories":[
{"name":"Active Directory",
"type":"CONNECTOR",
"implementationClass":"com.atlassian.crowd.integration.directory.connector.MicrosoftActiveDirectory"},{"name":"Atlassian Crowd",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"},{"name":"Crowd Internal",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"},{"name":"Delegated Auth Directory",
"type":"DELEGATING",
"implementationClass":"com.atlassian.crowd.integration.directory.delegated.DelegatedAuthenticationDirectory"},{"name":"Employees",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"}
{"name":"My Own Connector",
"type":"CUSTOM",
"implementationClass":"com.atlassian.crowd.integration.directory.custom.MyOwnConnector"}]}

Directory Information

URI /directory/DIRECTORY-KEY
where DIRECTORY-KEY is the directory name
Description Retrieves information about a specific directory.
URI Parameters None.
HTTP Methods
  • GET — Returns the directory information.

Example of a request for information about directory 'atlassian crowd':

http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd

Example of XML response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<directory>
  <name>Atlassian Crowd</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
</directory>

Elements in the response:

Element Description Attributes
directory A directory defined in Crowd.  
name The name of the directory, as defined in Crowd.  
type The Crowd directory type. Possible values are:  
implementationClass The Java class file that provides the methods for authentication, searching, and creation, deletion and updating the entities in the directory.  

Example of JSON response:

{"name":"Atlassian Crowd",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"}

User List

URI /directory/DIRECTORY-KEY/user
where DIRECTORY-KEY is the directory name
Description Lists all the users in the given directory and allows you to add a user to the list.
URI Parameters
  • ?search=SEARCHVALUE — This parameter is required on a GET request. This resource returns an HTTP 403 (access forbidden) if a GET request is sent to the URL without the search parameter. Replace SEARCHVALUE with your search term. The search term can be all or part of the username, name or email address. Leave the search term empty to return all users. Requesting all users is not recommended if your Crowd installation manages a large number of users, as this can result in severe performance degradation.
HTTP Methods
  • GET — Returns a list of users.
  • POST — Adds a user to the given directory. For the XML specification, refer to the user information resource.

Example of a search for users matching 'ad' in directory 'atlassian crowd':

http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user?search=ad

Example of XML response to the above request:

 <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<users>
 <user>
  <identifier>adent</identifier> 
  <username>adent</username> 
  <firstName>Arthur</firstName> 
  <lastName>Dent</lastName> 
  <displayName>Arthur Dent</displayName> 
  <emailAddress>adent@example.com</emailAddress> 
  </user>
 <user>
  <identifier>admin</identifier> 
  <username>admin</username> 
  <firstName>Admin</firstName> 
  <lastName>Administrator</lastName> 
  <displayName>Admin Administrator</displayName> 
  <emailAddress>admin@example.com</emailAddress> 
  </user>
</users>

Elements in the response:

Element Description Attributes
users A list of users in the Crowd directory.  
  Refer to the section on user information below for the elements describing each user.  

Example of JSON response for a list of users:

{"users":[
{"identifier":"adent",
"username":"adent",
"firstName":"Arthur",
"lastName":"Dent",
"displayName":"Arthur Dent",
"emailAddress":"adent@example.com"},
{"identifier":"admin",
"username":"admin",
"firstName":"Admin",
"lastName":"Administrator",
"displayName":"Admin Administrator",
"emailAddress":"admin@example.com"}]}

User Information

URI /directory/DIRECTORY-KEY/user/USER-KEY
where DIRECTORY-KEY is the directory name
and USER-KEY is the username
Description Retrieves or updates information about a specific user and allows deletion of the user from the given directory.
URI Parameters None.
HTTP Methods
  • GET — Returns information about the given user in the given directory.
  • PUT — Updates the user details.
  • DELETE — Removes the user from the directory.

Here is an example of a request for information on user 'adent' in directory 'atlassian crowd':

http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user/adent

The following cURL request deletes the user 'adent', using basic authentication where the username and password are both 'admin':

curl -X DELETE http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user/adent -u admin:admin

Example of XML response giving user information:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<user>
  <identifier>adent</identifier> 
  <username>adent</username> 
  <firstName>Arthur</firstName> 
  <lastName>Dent</lastName> 
  <displayName>Arthur Dent</displayName> 
  <emailAddress>adent@example.com</emailAddress> 
</user>

Elements in the response:

Element Description Attributes
user A user defined in a Crowd directory.  
identifier The user's username. Currently, this element contains the same value as the username element.  
username The user's username.  
firstName The user's first name.  
lastName The user's last name.  
displayName The user's full name, composed of first name plus last name.  
emailAddress The user's email address.  

Example of JSON response giving user information:

{"identifier":"adent",
"username":"adent",
"firstName":"Arthur",
"lastName":"Dent",
"displayName":"Arthur Dent",
"emailAddress":"adent@example.com"}

Group List

URI /directory/DIRECTORY-KEY/group
where DIRECTORY-KEY is the directory name
Description Lists all the groups in the given directory.
URI Parameters
  • ?search=SEARCHVALUE — This parameter is required on a GET request. This resource returns an HTTP 403 (access forbidden) if a GET request is sent to the URL without the search parameter. Replace SEARCHVALUE with your search term. The search term can be all or part of the group name. Leave the search term empty to return all groups.
HTTP Methods
  • GET — Returns a list of groups.
  • POST — Adds a group to the given directory. For the XML specification, refer to the group information resource.

Example of a search request for groups matching 'team' in directory 'atlassian crowd':

http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/group?search=team

Example of XML response to the above request:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<groups>
 <group>
  <identifier>my-team</identifier> 
  <name>my-team</name> 
  <description>My Team</description> 
  <type>GROUP</type> 
 </group>
 <group>
  <identifier>team2</identifier> 
  <name>team2</name> 
  <description>Team 2</description>
  <type>GROUP</type>  
 </group>
 <group>
  <identifier>team3</identifier> 
  <name>team3</name> 
  <description>Team 3</description> 
  <type>GROUP</type> 
 </group>
 <group>
  <identifier>teamlead</identifier> 
  <name>teamlead</name> 
  <description>Team Leader</description> 
  <type>LEGACY_ROLE</type> 
 </group>
</groups>

Elements in the response:

Element Description Attributes
groups A list of groups in the Crowd directory.  
  Refer to the section on group information below for the elements describing each group.  

Example of JSON response for a list of groups:

{"groups":[
{"identifier":"my-team",
"name":"my-team",
"description":"My Team",
"type":"GROUP"},
{"identifier":"team2",
"name":"team2",
"description":"Team 2",
"type":"GROUP"},
{"identifier":"team3",
"name":"team3",
"description":"Team 3",
"type":"GROUP"},
{"identifier":"teamlead",
"name":"teamlead",
"description":"Team Leader"
"type":"LEGACY_ROLE"}]}

Group Information

URI /directory/DIRECTORY-KEY/group/GROUP-KEY
where DIRECTORY-KEY is the directory name
and GROUP-KEY is the group name
Description Retrieves or updates information about a specific group.
URI Parameters None.
HTTP Methods
  • GET — Returns information about the given group in the given directory.
  • DELETE — Deletes the given group from the given directory.

Here is an example of a request for information on group 'my-team' in directory 'atlassian crowd':

http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/group/my-team

The following cURL request deletes the group 'my-team', using basic authentication where the username and password are both 'admin':

curl -X DELETE http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/group/my-team -u admin:admin

Example of XML response for group information:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<group>
  <identifier>my-team</identifier> 
  <name>my-team</name> 
  <description>My Team</description> 
  <type>GROUP</type> 
</group>

Elements in the response:

Element Description Attributes
group A group as defined in a Crowd directory.  
identifier The group name. Currently, this element contains the same value as the name element.  
name The group name.  
description A description of the group.  
type Indicates whether this item is a group or a role. Possible values are:
  • GROUP — The returned item is a group.
  • LEGACY_ROLE — The returned item is a role, as currently defined in Crowd.
 

Example of JSON response for group information:

{"identifier":"my-team",
"name":"my-team",
"description":"My Team",
"type":"GROUP"}

Group Membership for a User

URI /directory/DIRECTORY-KEY/user/USER-KEY/memberships
where DIRECTORY-KEY is the directory name
and USER-KEY is the username
Description Retrieves a list of the groups a given user belongs to, in the given directory.
URI Parameters None.
HTTP Methods
  • GET — Returns a list of groups that the user belongs to.

Here is an example of a request for the groups to which user 'adent' belongs, in directory 'atlassian crowd':

http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user/adent/memberships

Example of XML response for a list of group memberships:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<groups>
  <group>
   <identifier>my-team</identifier> 
   <name>my-team</name> 
   <description>My Team</description> 
   <type>GROUP</type> 
  </group>
  <group>
   <identifier>techwriter</identifier> 
   <name>techwriter</name> 
   <description>Technical writer</description> 
   <type>LEGACY_ROLE</type> 
  </group>
  <group>
   <identifier>confluence-users</identifier> 
   <name>confluence-users</name> 
   <description>Confluence users</description> 
   <type>GROUP</type> 
  </group>
</groups>

Elements in the response:

Element Description Attributes
groups A list of groups in the Crowd directory.  
  Refer to the section on group information above for the elements describing each group.  

Example of JSON response for a list of group members:

{"group":
[{"identifier":"my-team",
"name":"my-team",
"description":"My Team",
"type":"GROUP"},
{"identifier":"techwriter",
"name":"techwriter",
"description":"Technical writer",
"type":"LEGACY_ROLE"},
{"identifier":"confluence-users",
"name":"confluence-users",
"description":"Confluence users",
"type":"GROUP"}]}
RELATED TOPICS

Crowd REST APIs
Crowd Development Hub

Document generated by Confluence on Jul 30, 2009 01:30