groups/{groupid}/users (PUT)

Overview

Set the members for a group

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 Administrator access is required
Not Found 404 Requested group could not be found

Message Format

Input:

<users>
    <user id="{int}"/>
    ...
</users>

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

Note that this feature only updates the group user list. Additionally, the list of users passed does not append to the existing set, but replaces that set completely.

Use PUT:groups/{groupid} to modify the group role. 

C# Sample: Update a Group's Users

The following code example updates group with ID 2 to contain users with ID 2 and 3:

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc usersDoc = new XDoc("users")
    .Start("user")
        .Attr("id", 2)
    .End()
    .Start("user")
        .Attr("id", 3)
    .End();
p.At("groups", "2", "users").Put(usersDoc);

Sample Response from executing Code

<group id="2" href="http://deki-hayes/@api/deki/groups/2">
    <groupname>My Contributors Group</groupname> 
    <service.authentication id="1" href="http://deki-hayes/@api/deki/site/services/1" /> 
    <users count="2" href="http://deki-hayes/@api/deki/groups/2/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 Sample: Update a Group's Users

The following command will update a group (group ID = 1) with the users listed in newgroup.xml

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -T newgroup.xml -i http://192.168.168.110/@api/deki/groups/1/users

Implementation notes 

curl flags

-u
Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
-H
Adds a header or modifies an existing one. In this case, since an xml document is being sent, the content type must be set to "application/xml". The server will not accept the request otherwise.
-T file
Specifies a PUT request and XML document that contains the user data.
-i
Includes the HTTP response header in the output. Useful for debugging.

Permissions

ADMIN permission is required to execute above command. Otherwise, a 403 HTTP response (Forbidden) will be returned.

 

Example

We want to modify the group (group ID = 2) created here. Two users will be added, IDs 2 and 6, and user, ID 1, will be removed.

fabfour.xml

Content-Type: application/xml

<users>
	<user id="5"/>
	<user id="2"/>
	<user id="4"/>
	<user id="3"/>
	<user id="6"/>
</users>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -T fabfour.xml -i http://192.168.168.110/@api/deki/groups/2/users

HTTP Response Headers

HTTP/1.1 200 OK
Date: Thu, 14 Jan 2010 19:03:47 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 495
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<group id="2" href="http://192.168.168.110/@api/deki/groups/2">
  <groupname>the fab four</groupname>
  <service.authentication id="1" href="http://192.168.168.110/@api/deki/site/services/1"/>
  <users count="5" href="http://192.168.168.110/@api/deki/groups/2/users"/>
  <permissions.group>
    <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
    <role id="4" href="http://192.168.168.110/@api/deki/site/roles/4">Contributor</role>
  </permissions.group>
</group>