groups/{groupid}/users (PUT)
Overview
Set the members for a group
- REST Method: PUT
- 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 | 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>