groups/{groupid}/users (POST)

Last updated
Save as PDF

Overview

Add members to a group

REST Method: POST
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:

<users>
    <user id="{id}"/>
    <user id="{id}"/>
    ...
</users>

Output:

<group id="{int}" href="{uri}">
    <groupname>{text}</groupname> 
    <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

The passed in list of users are added to the existing member of the group

Curl Code Sample: Add Users to Group

The following command adds users listed in "addusers.xml" to a group (Group ID = 1).

Sample Code

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

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 a POST request and the file that contains a list of users.
-i: Includes the HTTP response header in the output. Useful for debugging.

Permissions

ADMIN permission is required to execute the above command. Otherwise, a 403 HTTP response (Forbidden) will be returned.

Example

The following example demonstrates how to add several users to a group (group ID = 21).

addtogroup.xml

Content-Type: application/xml

<users>
	<user id="90"/>
	<user id="88"/>
	<user id="89"/>
</users>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -d @addtogroup.xml -i http://192.168.59.128/@api/deki/groups/21/users

HTTP Response Headers

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2010 19:23:55 GMT
Server: Dream-HTTPAPI/2.0.0.17629 Microsoft-HTTPAPI/2.0
Content-Length: 485
Content-Type: application/xml; charset=utf-8
X-Data-Stats: request-time-ms=8; mysql-queries=8; mysql-time-ms=6;
X-Deki-Site: id="default"
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<group id="21" href="http://192.168.59.128/@api/deki/groups/21">
  <groupname>foo</groupname>
  <service.authentication id="1" href="http://192.168.59.128/@api/deki/site/services/1"/>
  <users count="3" href="http://192.168.59.128/@api/deki/groups/21/users"/>
  <permissions.group>
    <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
    <role id="4" href="http://192.168.59.128/@api/deki/site/roles/4">Contributor</role>
  </permissions.group>
</group>

Notes

If a user is already a member of a group, the request to add the specific user to the group will be ignored.
If one or more user IDs do not exist, the entire request will be ignored.