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>