groups (POST)

Overview

Add or modify a group

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