Rest Users » History » Version 7
Version 6 (Jean-Philippe Lang, 2012-06-03 15:19) → Version 7/27 (Jean-Philippe Lang, 2012-06-03 16:09)
h1. Users
{{>toc}}
h2. /users.:format
h3. Listing users
GET /users.xml
Returns users.
h2. Showing a list of users.
+Example+: user
GET /users.xml /users/[id].xml
h3. POST
Creates a user.
+Parameters+:
* @user@ (required): a hash of Returns the user attributes, including: of given id.
* @login@ (required): the user login
* @password@: the user password
* @firstname@ (required)
* @lastname@ (required)
* @mail@ (required)
* @auth_source_id@: authentication mode id
+Example+:
<pre>
POST /users.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>
</pre>
+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 /users/current.xml
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@
* @groups@ (added in 2.1)
+Examples+: +Example+:
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>
<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>
h2. Creating a user
POST /users.xml
h3. PUT
Updates 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
+Example+:
<pre>
POST /users.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>
</pre>
+Response+:
* @201 Created@: user was created
* @422 Unprocessable Entity@: user was not created due to validation failures (response body contains the error messages)
h2. Updating a user
PUT /users/20.xml /users/[id].xml
+Parameters+:
* @user@ (required): a hash of the user attributes (same as for user creation)
h3. DELETE Updates the user of given id.
Deletes h2. Deleting a user.
+Example+: user
DELETE /users/20.xml /users/[id].xml
Deletes the user of given id.
+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.
{{>toc}}
h2. /users.:format
h3. Listing users
GET /users.xml
Returns users.
h2. Showing a list of users.
+Example+: user
GET /users.xml /users/[id].xml
h3. POST
Creates a user.
+Parameters+:
* @user@ (required): a hash of Returns the user attributes, including: of given id.
* @login@ (required): the user login
* @password@: the user password
* @firstname@ (required)
* @lastname@ (required)
* @mail@ (required)
* @auth_source_id@: authentication mode id
+Example+:
<pre>
POST /users.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>
</pre>
+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 /users/current.xml
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@
* @groups@ (added in 2.1)
+Examples+: +Example+:
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>
<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>
h2. Creating a user
POST /users.xml
h3. PUT
Updates 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
+Example+:
<pre>
POST /users.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>
</pre>
+Response+:
* @201 Created@: user was created
* @422 Unprocessable Entity@: user was not created due to validation failures (response body contains the error messages)
h2. Updating a user
PUT /users/20.xml /users/[id].xml
+Parameters+:
* @user@ (required): a hash of the user attributes (same as for user creation)
h3. DELETE Updates the user of given id.
Deletes h2. Deleting a user.
+Example+: user
DELETE /users/20.xml /users/[id].xml
Deletes the user of given id.
+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.