groups/{groupid} (GET)

Overview

Retrieve group information

REST Method: GET
Method Access: public

Uri Parameters

Name	Type	Description
groupid	string	either an integer group ID or "=" followed by a double uri-encoded group name

Query Parameters

Name	Type	Description
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
Not Found	404	Requested group could not be found

Message Format

Output:

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

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 GET:groups to retrieve a list of groups defined across the site.

C# Code Sample: Retrieve Group Info

The following code example retrieves the group called "My Contributors Group":

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
p.At("groups", "=My%2520Contributors%2520Group").Get();

Sample Response from executing Code

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

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

Implementation notes

Add notes about requirements or config values

Curl Code Sample: Retrieve Group Info

The following command retrieves information of the group "foo":

Sample Code

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

Sample Response from executing Code

group_name = test

Content-Type: application/xml

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

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.

Groups

To view a list of all groups, follow the instructions here.