POST:groups

Overview

public. Add or modify a group

Message Format

Input:

<group id="{int}">
    <name>{text}</name>
    <service.authentication id="{int}" />
    <users>
        <user id="{int}"/>
        ...
    </users>
    <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

If group ID is unspecified, a new group will be created.  If group ID is specified, the role of the existing group will be updated.

If service.authentication is unspecified, the local authentication service is assumed.  Otherwise, if an external authentication service is used, the authpassword and authusername query parameters will be used to login.

The role name must match one of the roles defined by GET:site/roles.

Code Samples

The following code example creates a new group called "My Contributors Group" with the Contributor role.  The new group uses the local authentication service and has two users:

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc groupDoc = new XDoc("group")
	.Elem("name", "My Contributors Group")
	.Start("permissions.group")
		.Elem("role", "Contributor")
	.End()
	.Start("users")
		.Start("user").Attr("id", 1).End()
		.Start("user").Attr("id", 2).End()
	.End();
p.At("groups").Post(groupDoc);

Sample response indicating that the group was successfully created:

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