groups (POST)

Overview

Add or modify a group

REST Method: POST
Method Access: public

Query Parameters

Name	Type	Description
authenticate	bool?	Force authentication for request (default: false)
authpassword	string?	Password to use for verification with external authentication service
authusername	string?	Username to use for verification with external authentication service

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
Conflict	409	Group already exists

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.

C# Code Sample: Create a New Group

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:

Sample Code

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

Curl Code Sample: Create a New Group

The following command creates a group with the members listed in the file "group.xml".

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -d @group.xml -i http://mindtouch.address/@api/deki/groups

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.
-d @file: Specifies the .xml file 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

The following demonstrates how to create a group. The group information is outlined in fabfour.xml.

fabfour.xml

Content-Type: application/xml

<group>
    <name>the fab four</name>
    <users>
	<user id="5"/>
	<user id="1"/>
	<user id="4"/>
	<user id="3"/>
    </users>
</group>

Command Line

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

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 12 Jan 2010 22:21:28 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="4" 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>

Notes

Attempting to create a group with the same name as an existing group will return a 409 HTTP response (Conflict).