Project

General

Profile

Rest Users » History » Revision 10

Revision 9 (Jean-Baptiste Barth, 2013-05-05 10:30) → Revision 10/30 (Jean-Baptiste Barth, 2013-05-05 10:40)

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) 
 * @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 

 +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> 

 JSON 

 <pre> 
 { 
     "user": { 
         "login": "jplang", 
         "firstname": "Jean-Philippe", 
         "lastname": "Lang", 
         "mail": "jp_lang@yahoo.fr", 
         "password": "secret" 
     } 
 } 
 </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 

 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+: 

   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> 

 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.