groups (GET)

Overview

Retrieve list of groups.

REST Method: GET
Method Access: public

Query Parameters

Name	Type	Description
authprovider	int?	Return groups belonging to given authentication service id
groupnamefilter	string?	Search for groups by name or part of a name
limit	string?	Maximum number of items to retrieve. Must be a positive number or 'all' to retrieve all items. (default: 100)
sortby	{id, name, role, service}?	Sort field. Prefix value with '-' to sort descending. default: No sorting
offset	int?	Number of items to skip. Must be a positive number or 0 to not skip any. (default: 0)
authenticate	bool?	Force authentication for request (default: false)

Return Codes

Name	Value	Description
OK	200	Request completed successfully
Bad Request	400	Invalid input parameter or request body
Forbidden	403	Read access is required

Message Format

Output:

<groups count="{int}" href="{uri}">
    <group id="{int}" href="{uri}">
        <groupname>{text}</groupname> 
        <service.authentication id="{int}" href="{uri}" /> 
        <users count="{int}" href="{uri}" /> 
        <permissions.group>
            <operations mask="{int}">{text}</operations> 
            <role id="{int}" href="{uri}">{text}</role> 
        </permissions.group>
    </group>
</groups>

Implementation Notes

Groups provide the ability to associate a collection of users with a predefined role. Use GET:site/roles to retrieve a list of all roles currently defined on the site.

Use POST:groups to add or modify a group and DELETE:groups/{groupid} to remove a specified group.

C# Code Sample: Retrieve Groups

The following code example retrieves all groups defined for the site:

Sample Code

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
p.At("groups").Get();

Sample Response from executing Code

Sample response indicating that there is one group. This group is associated with the local authentication service, contains one user, and has the Contributor role:

<groups count="1" href="http://help.mindtouch.us/@api/deki/groups">
    <group id="1" href="http://help.mindtouch.us/@api/deki/groups/1">
        <groupname>My Contributors Group</groupname> 
        <service.authentication id="1" href="http://help.mindtouch.us/@api/deki/site/services/1" /> 
        <users count="1" href="http://help.mindtouch.us/@api/deki/groups/1/users" /> 
        <permissions.group>
            <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations> 
            <role id="4" href="http://help.mindtouch.us/@api/deki/site/roles/4">Contributor</role> 
        </permissions.group>
    </group>
</groups>

Implementation notes

Add notes about requirements or config values

Curl Code Sample: Retrieve Groups

The following command retrieves a list and information of all existing groups:

Sample Code

curl -u username:password -i http://mindtouch.address/@api/deki/groups

Sample Response from executing Code

The site has 1 group:

Content-Type: application/xml

<groups count="1" querycount="1" totalcount="1" href="http://192.168.59.128/@api/deki/groups">
  <group id="22" href="http://192.168.59.128/@api/deki/groups/22">
    <groupname>test</groupname>
    <service.authentication id="1" href="http://192.168.59.128/@api/deki/site/services/1"/>
    <users href="http://192.168.59.128/@api/deki/groups/22/users"/>
    <permissions.group>
      <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
      <role id="4" href="http://192.168.59.128/@api/deki/site/roles/4">Contributor</role>
    </permissions.group>
  </group>
</groups>

Implementation notes

curl flags

-u: Provides external user authentication. Note that if anonymous access is available and authentication is not forced, this flag may be omitted.
-i: Outputs the HTTP response headers. Useful for debugging.