Rest Users » History » Version 16

Version 15 (Go MAEDA, 2017-05-11 08:08) → Version 16/25 (Toshi MARUYAMA, 2017-05-12 05:44)

h1. Users

{{>toc}}

h2. /users.:format

h3. GET

Returns a list of users.

+Example+:

GET /users.xml

Optional filters:

* @status@: get only users with the given status. See "app/models/principal.rb":/projects/redmine/repository/entry/trunk/app/models/principal.rb#L22-25 for a list of available statuses. Default is @1@ (active users). Possible values are:
** @1@: Active (User can login and use their account)
** @2@: Registered (User has registered but not yet confirmed their email address or was not yet activated by an administrator. User can not login)
** @3@: Locked (User was once active and is now locked, User can not login)
* @name@: filter users on their login, firstname, lastname and mail ; if the pattern contains a space, it will also return users whose firstname match the first word or lastname match the second word.
* @group_id@: get only users who are members of the given group

h3. POST

Creates a user.

+Parameters+:

* @user@ (required): a hash of the user attributes, including:

* @login@ (required): the user login
* @password@: the user password
* @firstname@ (required)
* @lastname@ (required)
* @mail@ (required)
* @auth_source_id@: authentication mode id
* @mail_notification@: only_my_events, none, etc.
* @must_change_passwd@: true or false
* @send_information@: true of false : Send acocunt information to the user

+Example+:

<pre>
POST /users.xml

<pre><code class="xml">
<?xml version="1.0" encoding="ISO-8859-1" ?>
<user>
<login>jplang</login>
<firstname>Jean-Philippe</firstname>
<lastname>Lang</lastname>
<password>secret</password>
<mail>jp_lang@yahoo.fr</mail>
<auth_source_id>2</auth_source_id>
</user>
</code></pre> &lt;/pre&gt;

JSON

<pre><code class="json"> &lt;pre&gt;
{
"user": {
"login": "jplang",
"firstname": "Jean-Philippe",
"lastname": "Lang",
"mail": "jp_lang@yahoo.fr",
"password": "secret"
}
}
</code></pre> &lt;/pre&gt;

+Response+:

* @201 Created@: user was created
* @422 Unprocessable Entity@: user was not created due to validation failures (response body contains the error messages)

h2. /users/:id.:format

h3. GET

Returns the user details. You can use @/users/current.:format@ for retrieving the user whose credentials are used to access the API.

+Parameters+:

* @include@ (optional): a coma separated list of associations to include in the response:

* @memberships@ : adds extra information about user's memberships and roles on the projects
* @groups@ (added in 2.1) : adds extra information about user's groups

+Examples+:

GET /users/current.xml

Returns the details about the current user.

GET /users/3.xml?include=memberships,groups

Returns the details about user ID 3, and additional detail about the user's project memberships.

+Reponse+:

<pre>
<user>
<id>3</id>
<login>jplang</login>
<firstname>Jean-Philippe</firstname>
<lastname>Lang</lastname>
<mail>jp_lang@yahoo.fr</mail>
<created_on>2007-09-28T00:16:04+02:00</created_on>
<last_login_on>2011-08-01T18:05:45+02:00</last_login_on>
<api_key>ebc3f6b781a6fb3f2b0a83ce0ebb80e0d585189d</api_key>
<status>1</status>
<custom_fields type="array" />
<memberships type="array">
<membership>
<project name="Redmine" id="1"/>
<roles type="array">
<role name="Administrator" id="3"/>
<role name="Contributor" id="4"/>
</roles>
</membership>
</memberships>
<groups type="array">
<group id="20" name="Developers"/>
</groups>
</user>
</pre>

Depending on the status of the user who makes the request, you can get some more details:
* @api_key@ : the API key of the user, visible for admins and for yourself (added in 2.3.0)
* @status@ : a numeric id representing the status of the user, visible for admins only (added in 2.4.0). See "app/models/principal.rb":/projects/redmine/repository/entry/trunk/app/models/principal.rb#L22-25 for a list of available statuses.

h3. PUT

Updates a user.

+Example+:

PUT /users/20.xml

+Parameters+:

* @user@ (required): a hash of the user attributes (same as for user creation)

h3. DELETE

Deletes a user.

+Example+:

DELETE /users/20.xml

+Response+:

* @200 OK@: user was deleted

h2. See also

* The [[Rest_Memberships|Memberships API]] for adding or removing a user from a project.
* The [[Rest_Groups|Groups API]] for adding or removing a user from a group.