Skip to main content

users/{userid} (PUT) (TCS)

Overview

Modify an existing user

  • REST Method: PUT
  • Method Access: public

Uri Parameters

Name Type Description
userid string either an integer user ID, "current", or "=" followed by a double uri-encoded user name

Query Parameters

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

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 Administrator access or account owner is required
Not Found 404 Requested user could not be found
Conflict 409 Username conflicts with an existing username

Message Format

Input: 

<user>
    <username>{text}</username> 
    <email>{text}</email> 
    <fullname>{text}</fullname> 
    <status>{active|inactive}</status> 
    <service.authentication id="{int}" /> 
    <permissions.user> 
        <role>{text}</role> 
    </permissions.user> 
</user>

Output: 

<user id="{int}" href="{uri}">
    <nick>{text}</nick> 
    <username>{text}</username> 
    <email>{text}</email> 
    <page.home id="{int}" href="{int}">
        <title>{text}</title> 
        <path>{text}</path> 
    </page.home>
    <fullname>{text}</fullname> 
    <status>{active|inactive}</status> 
    <date.lastlogin>{date}</date.lastlogin> 
    <service.authentication id="{int}" href="{uri]" /> 
    <permissions.user>
        <operations mask="{int}">{text}</operations> 
        <role id="{int}" href="{uri}">{text}</role> 
    </permissions.user>
    <permissions.effective>
        <operations mask="{int}">{text}</operations> 
    </permissions.effective>
    <groups count="{int}" href="{uri}">  
        <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>  
    ...
    </groups> 
</user>

Implementation Notes

Note that it is not possible to modify an existing user's authentication service. 

Use PUT:users/{userid}/password to change the user password.

C# Sample: Modifying a User

The following code example modifies "newuser1":

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc usersDoc = new XDoc("user")
    .Elem("email", "newemail@mindtouch.com")
    .Elem("fullname", "new full name")
    .Start("permissions.user")
        .Elem("role", "Viewer")
    .End();
p.At("users", "=newuser1").Put(usersDoc);

Sample Response from executing Code

<user id="6" href="http://deki-hayes/@api/deki/users/6">
    <nick>newuser1</nick>
    <username>newuser1</username>
    <email>newemail@mindtouch.com</email>
    <fullname>new full name</fullname>
    <status>active</status>
    <date.lastlogin>2007-09-06T00:56:51Z</date.lastlogin>
    <service.authentication id="1" href="http://deki-hayes/@api/deki/site/services/1" />
    <permissions.user>
        <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations> 
        <role id="3" href="http://deki-hayes/@api/deki/site/roles/3">Viewer</role> 
    </permissions.user>
    <permissions.effective>
        <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations> 
    </permissions.effective>
    <groups /> 
</user>

Implementation notes 

Add notes about requirements or config values.

Curl Sample: Modifying a User

The following command modifies an existing user (user ID = 1) with the user data in "user.xml".

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -T user.xml -i http://mindtouch.address/@api/deki/users/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 command and 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

We want to play a prank on a user with user ID = 3. The following xml document contains the new information with which will modify the user.

modifyuser.xml

Content-Type: application/xml

<user>
    <username>Amanda Hug and Kiss</username> 
    <email>moes@tavern.com</email> 
    <fullname>Amanda Hug and Kiss</fullname> 
    <status>active</status> 
</user>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -T modifyuser.xml -i http://192.168.168.110/@api/deki/users/3

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 12 Jan 2010 21:41:18 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 1554
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<user id="3" href="http://192.168.168.110/@api/deki/users/3">
  <nick>Amanda Hug and Kiss</nick>
  <username>Amanda Hug and Kiss</username>
  <email>moes@tavern.com</email>
  <hash.email>71bb00a704247d31bef82ffd2cc37476</hash.email>
  <uri.gravatar>http://www.gravatar.com/avatar/71bb00a704247d31bef82ffd2cc37476</uri.gravatar>
  <date.created>2010-01-04T22:55:32Z</date.created>
  <fullname>Amanda Hug and Kiss</fullname>
  <status>active</status>
  <date.lastlogin>2010-01-04T22:55:31Z</date.lastlogin>
  <language/>
  <timezone/>
  <service.authentication id="1" href="http://192.168.168.110/@api/deki/site/services/1"/>
  <permissions.user>
    <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.user>
  <permissions.effective>
    <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
  </permissions.effective>
  <groups>
    <group id="1" href="http://192.168.168.110/@api/deki/groups/1">
      <groupname>l33t group</groupname>
      <service.authentication id="1" href="http://192.168.168.110/@api/deki/site/services/1"/>
      <users count="3" href="http://192.168.168.110/@api/deki/groups/1/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>
  </groups>
  <properties href="http://192.168.168.110/@api/deki/users/3/properties"/>
</user>
  • Was this article helpful?