groups/{groupid} (PUT)
Overview
Modify an existing 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:
<group id="{int}"> <name>{text}</name> <permissions.group> <role>{text}</role> </permissions.group> </group>
Output:
<group id="{int}" href="{uri}"> <name>{text}</name> <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
- This feature may be used for updating the group role and renaming the group.
- Use Post:groups/{groupid}/users to add and remove users from a group.
- The role name must match one of the roles defined by GET:site/roles.
- External groups may not be renamed
C# Sample: Modify a Group's Role
The following code example updates group with ID 2 to have the Contributor role:
Sample Code
Plug p = Plug.New("http://deki-hayes/@api/deki"); p.At("users", "authenticate").WithCredentials("admin", "password").Get(); XDoc groupDoc = new XDoc("group") .Start("permissions.group") .Elem("role", "Contributor") .End(); p.At("groups", "2").Put(groupDoc);
Sample Response from executing Code
<group id="2" href="http://deki-hayes/@api/deki/groups/2"> <name>My Contributors Group</name> <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: Modify a Group's Role
The following command sets a group's (group ID = 1) role to the one listed in "grouprole.xml".
Sample Code
curl -u admin:password -H "Content-Type: application/xml" -T grouprole.xml -i http://192.l68.168.110/@api/deki/groups/1
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 role of a group (group ID = 2) created here. Here are some of the roles that are packaged with Expert: Contributer, Viewer, Guest, and Admin. The group we wish to modify has the role of "Contributer". In this example, it will be changed to "Viewer".
fabfour.xml
Content-Type: application/xml
<group> <permissions.group> <role>Viewer</role> </permissions.group> </group>
Command Line
curl -u admin:password -H "Content-Type: application/xml" -T fabfourrole.xml -i http://192.168.168.110/@api/deki/groups/2
HTTP Response Headers
HTTP/1.1 200 OK Date: Thu, 14 Jan 2010 19:48:33 GMT Server: Dream-HTTPAPI/1.7.2.17433 X-Deki-Site: id="default" Content-Type: application/xml; charset=utf-8 Content-Length: 449 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="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations> <role id="3" href="http://192.168.168.110/@api/deki/site/roles/3">Viewer</role> </permissions.group> </group>