users (GET)

Last updated
Save as PDF

Overview

Retrieve list of users.

REST Method: GET
Method Access: public

Query Parameters

Name	Type	Description
authenticate	bool?	Force authentication for request (default: false)
verbose	bool?	Return detailed user information. (default: true)
sortby	{id, username, nick, email, fullname, date.lastlogin, status, role, service, date.created}?	Sort field. Prefix value with '-' to sort descending. default: No sorting
offset	int?	Number of items to skip. Must be a positive number or 0 to not skip any. (default: 0)
limit	string?	Maximum number of items to retrieve. Must be a positive number or 'all' to retrieve all items. (default: 100)
seatfilter	string?	Search for users with or without seats (one of "seated", "unseated", or "recommended"; default: none)
activatedfilter	bool?	Search for users by their active status
rolefilter	string?	Search for users by a role name
authprovider	int?	Return users belonging to given authentication service id
usernameemailfilter	string?	Search for users by name and email or part of a name and email
fullnamefilter	string?	Search for users full name starting with supplied text
usernamefilter	string?	Search for users name starting with supplied text

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Forbidden	403	Read access is required

Message Format

Output:

<users count="{int}" href="{uri}">
    <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 /> 
        <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>
    ...
</users>

Implementation Notes

User POST:users to add or modify users.

C# Code Sample: Retrieve User List

The following code example retrieves a list of users:

Sample Code

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
p.At("users").Get();

Sample Response from executing Code

Sample response indicating that there are two users, Admin and Anonymous:

<users count="2" href="http://help.mindtouch.us/@api/deki/users">
    <user id="1" href="http://help.mindtouch.us/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@mindtouch.com</email>
        <page.home id="30" href="http://help.mindtouch.us/@api/deki/pages/30">
            <title>User:Admin</title>
            <path>User:Admin</path>
        </page.home>
        <fullname></fullname>
        <status>active</status>
        <date.lastlogin>2007-08-30T17:26:32Z</date.lastlogin>
        <service.authentication id="1" href="http://help.mindtouch.us/@api/deki/site/services/1" />
        <permissions.user>
            <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
            <role id="5" href="http://help.mindtouch.us/@api/deki/site/roles/5">Admin</role>
        </permissions.user>
        <permissions.effective>
            <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
        </permissions.effective>
        <groups />
    </user>
    <user id="2" href="http://help.mindtouch.us/@api/deki/users/2">
        <nick>Anonymous</nick>
        <username>Anonymous</username>
        <email></email>
        <fullname>Anonymous User</fullname>
        <status>active</status>
        <date.lastlogin>2007-08-30T17:26:12Z</date.lastlogin>
        <service.authentication id="1" href="http://help.mindtouch.us/@api/deki/site/services/1" />
        <permissions.user>
            <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
            <role id="3" href="http://help.mindtouch.us/@api/deki/site/roles/3">Viewer</role>
        </permissions.user>
        <permissions.effective>
            <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
        </permissions.effective>
        <groups />
    </user>
</users>

Curl Code Sample: Retrieve User List

The following command retrieves a list of all users registered to the site:

Sample Code

curl -u username:password -i http://mindtouch.address/@api/deki/users

Sample Response from executing Code

Sample response with a looong list of users (only a couple shown).

Content-Type: application/xml

<users count="90" querycount="90" totalcount="90" href="http://192.168.59.128/@api/deki/users">
  <user id="1" href="http://192.168.59.128/@api/deki/users/1">
    <nick>Admin</nick>
    <username>Admin</username>
    <email hidden="true"/>
    <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
    <date.created>0001-01-01T00:00:00Z</date.created>
    <page.home id="37" href="http://192.168.59.128/@api/deki/pages/37?redirects=0">
      <uri.ui>http://192.168.59.128/User:Admin</uri.ui>
      <title>User:Admin</title>
      <path>User:Admin</path>
      <namespace>user</namespace>
    </page.home>
    <fullname/>
    <status>active</status>
    <date.lastlogin>2010-02-02T19:44:00Z</date.lastlogin>
    <language/>
    <timezone/>
    <service.authentication id="1" href="http://192.168.59.128/@api/deki/site/services/1"/>
    <permissions.user>
      <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
      <role id="5" href="http://192.168.59.128/@api/deki/site/roles/5">Admin</role>
    </permissions.user>
    <permissions.effective>
      <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
    </permissions.effective>
    <groups/>
    <properties href="http://192.168.59.128/@api/deki/users/1/properties"/>
  </user>
  <user id="2" href="http://192.168.59.128/@api/deki/users/2">
    <nick>Anonymous</nick>
    <username>Anonymous</username>
    <email/>
    <hash.email>d41d8cd98f00b204e9800998ecf8427e</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/d41d8cd98f00b204e9800998ecf8427e</uri.gravatar>
    <date.created>0001-01-01T00:00:00Z</date.created>
    <fullname>Anonymous User</fullname>
    <status>active</status>
    <date.lastlogin>2010-02-02T19:51:58Z</date.lastlogin>
    <language/>
    <timezone/>
    <service.authentication id="1" href="http://192.168.59.128/@api/deki/site/services/1"/>
    <permissions.user>
      <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
      <role id="3" href="http://192.168.59.128/@api/deki/site/roles/3">Viewer</role>
    </permissions.user>
    <permissions.effective>
      <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
    </permissions.effective>
    <groups/>
    <properties count="0" href="http://192.168.59.128/@api/deki/users/2/properties"/>
  </user>

  ...

</users>

Implementation notes

curl flags

-u: Provides external user authentication. Note that if anonymous access is available and authentication is not forced, this flag may be omitted.
-i: Outputs the HTTP response headers. Useful for debugging.