Rest Users » History » Version 20

Cyril Jouve, 2017-08-30 11:01

1 1 Jean-Philippe Lang
h1. Users
2 1 Jean-Philippe Lang
3 3 Jean-Philippe Lang
{{>toc}}
4 3 Jean-Philippe Lang
5 7 Jean-Philippe Lang
h2. /users.:format
6 1 Jean-Philippe Lang
7 7 Jean-Philippe Lang
h3. GET
8 7 Jean-Philippe Lang
9 7 Jean-Philippe Lang
Returns a list of users.
10 7 Jean-Philippe Lang
11 20 Cyril Jouve
This endpoint requires admin privileges.
12 20 Cyril Jouve
13 7 Jean-Philippe Lang
+Example+:
14 7 Jean-Philippe Lang
15 1 Jean-Philippe Lang
  GET /users.xml
16 1 Jean-Philippe Lang
17 10 Jean-Baptiste Barth
Optional filters:
18 10 Jean-Baptiste Barth
19 13 Go MAEDA
* @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:
20 13 Go MAEDA
** @1@: Active (User can login and use their account)
21 13 Go MAEDA
** @2@: Registered (User has registered but not yet confirmed their email address or was not yet activated by an administrator. User can not login)
22 13 Go MAEDA
** @3@: Locked (User was once active and is now locked, User can not login)
23 10 Jean-Baptiste Barth
* @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.
24 10 Jean-Baptiste Barth
* @group_id@: get only users who are members of the given group
25 10 Jean-Baptiste Barth
26 7 Jean-Philippe Lang
h3. POST
27 1 Jean-Philippe Lang
28 7 Jean-Philippe Lang
Creates a user.
29 1 Jean-Philippe Lang
30 20 Cyril Jouve
This endpoint requires admin privileges.
31 20 Cyril Jouve
32 7 Jean-Philippe Lang
+Parameters+:
33 1 Jean-Philippe Lang
34 7 Jean-Philippe Lang
* @user@ (required): a hash of the user attributes, including:
35 1 Jean-Philippe Lang
36 7 Jean-Philippe Lang
  * @login@ (required): the user login
37 7 Jean-Philippe Lang
  * @password@: the user password
38 7 Jean-Philippe Lang
  * @firstname@ (required)
39 7 Jean-Philippe Lang
  * @lastname@ (required)
40 7 Jean-Philippe Lang
  * @mail@ (required)
41 7 Jean-Philippe Lang
  * @auth_source_id@: authentication mode id
42 12 Matt Wiseley
  * @mail_notification@: only_my_events, none, etc.
43 12 Matt Wiseley
  * @must_change_passwd@: true or false
44 19 F. P.
  * @generate_password@: true or false
45 19 F. P.
* @send_information@: true or false : Send acocunt information to the user
46 19 F. P.
47 1 Jean-Philippe Lang
48 7 Jean-Philippe Lang
+Example+:
49 1 Jean-Philippe Lang
50 17 Toshi MARUYAMA
<pre>
51 7 Jean-Philippe Lang
POST /users.xml
52 17 Toshi MARUYAMA
</pre>
53 1 Jean-Philippe Lang
54 16 Toshi MARUYAMA
<pre><code class="xml">
55 7 Jean-Philippe Lang
<?xml version="1.0" encoding="ISO-8859-1" ?>
56 7 Jean-Philippe Lang
<user>
57 7 Jean-Philippe Lang
  <login>jplang</login>
58 7 Jean-Philippe Lang
  <firstname>Jean-Philippe</firstname>
59 7 Jean-Philippe Lang
  <lastname>Lang</lastname>
60 7 Jean-Philippe Lang
  <password>secret</password>
61 7 Jean-Philippe Lang
  <mail>jp_lang@yahoo.fr</mail>
62 7 Jean-Philippe Lang
  <auth_source_id>2</auth_source_id>
63 7 Jean-Philippe Lang
</user>
64 16 Toshi MARUYAMA
</code></pre>
65 7 Jean-Philippe Lang
66 8 Lutz Horn
JSON
67 8 Lutz Horn
68 16 Toshi MARUYAMA
<pre><code class="json">
69 8 Lutz Horn
{
70 8 Lutz Horn
    "user": {
71 8 Lutz Horn
        "login": "jplang",
72 8 Lutz Horn
        "firstname": "Jean-Philippe",
73 8 Lutz Horn
        "lastname": "Lang",
74 8 Lutz Horn
        "mail": "jp_lang@yahoo.fr",
75 8 Lutz Horn
        "password": "secret"
76 8 Lutz Horn
    }
77 8 Lutz Horn
}
78 16 Toshi MARUYAMA
</code></pre>
79 8 Lutz Horn
80 7 Jean-Philippe Lang
+Response+:
81 7 Jean-Philippe Lang
82 7 Jean-Philippe Lang
  * @201 Created@: user was created
83 7 Jean-Philippe Lang
  * @422 Unprocessable Entity@: user was not created due to validation failures (response body contains the error messages)
84 7 Jean-Philippe Lang
85 7 Jean-Philippe Lang
h2. /users/:id.:format
86 7 Jean-Philippe Lang
87 7 Jean-Philippe Lang
h3. GET
88 7 Jean-Philippe Lang
89 7 Jean-Philippe Lang
Returns the user details. You can use @/users/current.:format@ for retrieving the user whose credentials are used to access the API.
90 7 Jean-Philippe Lang
91 20 Cyril Jouve
This endpoint can be used by admin or non admin but the returned fields will depend on the privileges of the requesting user.
92 20 Cyril Jouve
93 20 Cyril Jouve
If the user doing the request is admin, a complete user object is always returned (see exemple below).
94 20 Cyril Jouve
95 20 Cyril Jouve
If the user doing the request is not admin, it depends on the requested user:
96 20 Cyril Jouve
97 20 Cyril Jouve
  * if the user is not locked and is not admin, the endpoint returns a user object with the fields firstname, lastname, mail, created_on
98 20 Cyril Jouve
  * if the user is not locked and is admin, the endpoint returns a user object with the fields firstname, lastname, created_on, last_login_on
99 20 Cyril Jouve
  * if the user is locked, the endpoint returns 404 status code
100 20 Cyril Jouve
101 3 Jean-Philippe Lang
+Parameters+:
102 1 Jean-Philippe Lang
103 1 Jean-Philippe Lang
* @include@ (optional): a coma separated list of associations to include in the response:
104 1 Jean-Philippe Lang
105 11 Jean-Baptiste Barth
  * @memberships@ : adds extra information about user's memberships and roles on the projects
106 11 Jean-Baptiste Barth
  * @groups@ (added in 2.1) : adds extra information about user's groups
107 1 Jean-Philippe Lang
108 7 Jean-Philippe Lang
+Examples+:
109 1 Jean-Philippe Lang
110 7 Jean-Philippe Lang
  GET /users/current.xml
111 7 Jean-Philippe Lang
112 7 Jean-Philippe Lang
Returns the details about the current user.
113 7 Jean-Philippe Lang
114 1 Jean-Philippe Lang
  GET /users/3.xml?include=memberships,groups
115 1 Jean-Philippe Lang
116 1 Jean-Philippe Lang
Returns the details about user ID 3, and additional detail about the user's project memberships.
117 1 Jean-Philippe Lang
118 18 Toshi MARUYAMA
+Response+:
119 1 Jean-Philippe Lang
120 18 Toshi MARUYAMA
<pre><code class="xml">
121 1 Jean-Philippe Lang
<user>
122 1 Jean-Philippe Lang
  <id>3</id>
123 1 Jean-Philippe Lang
  <login>jplang</login>
124 1 Jean-Philippe Lang
  <firstname>Jean-Philippe</firstname>
125 1 Jean-Philippe Lang
  <lastname>Lang</lastname>
126 1 Jean-Philippe Lang
  <mail>jp_lang@yahoo.fr</mail>
127 1 Jean-Philippe Lang
  <created_on>2007-09-28T00:16:04+02:00</created_on>
128 1 Jean-Philippe Lang
  <last_login_on>2011-08-01T18:05:45+02:00</last_login_on>
129 14 Go MAEDA
  <api_key>ebc3f6b781a6fb3f2b0a83ce0ebb80e0d585189d</api_key>
130 14 Go MAEDA
  <status>1</status>
131 5 Rick Mason
  <custom_fields type="array" />
132 1 Jean-Philippe Lang
  <memberships type="array">
133 4 Jean-Philippe Lang
    <membership>
134 4 Jean-Philippe Lang
      <project name="Redmine" id="1"/>
135 4 Jean-Philippe Lang
      <roles type="array">
136 4 Jean-Philippe Lang
        <role name="Administrator" id="3"/>
137 4 Jean-Philippe Lang
        <role name="Contributor" id="4"/>
138 1 Jean-Philippe Lang
      </roles>
139 1 Jean-Philippe Lang
    </membership>
140 4 Jean-Philippe Lang
  </memberships>
141 4 Jean-Philippe Lang
  <groups type="array">
142 4 Jean-Philippe Lang
    <group id="20" name="Developers"/>
143 4 Jean-Philippe Lang
  </groups>
144 4 Jean-Philippe Lang
</user>
145 18 Toshi MARUYAMA
</code></pre>
146 4 Jean-Philippe Lang
147 9 Jean-Baptiste Barth
Depending on the status of the user who makes the request, you can get some more details:
148 9 Jean-Baptiste Barth
* @api_key@ : the API key of the user, visible for admins and for yourself (added in 2.3.0)
149 9 Jean-Baptiste Barth
* @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.
150 9 Jean-Baptiste Barth
151 7 Jean-Philippe Lang
h3. PUT
152 4 Jean-Philippe Lang
153 7 Jean-Philippe Lang
Updates a user.
154 4 Jean-Philippe Lang
155 20 Cyril Jouve
This endpoint requires admin privileges.
156 20 Cyril Jouve
157 1 Jean-Philippe Lang
+Example+:
158 1 Jean-Philippe Lang
159 7 Jean-Philippe Lang
  PUT /users/20.xml
160 1 Jean-Philippe Lang
161 1 Jean-Philippe Lang
+Parameters+:
162 1 Jean-Philippe Lang
163 1 Jean-Philippe Lang
* @user@ (required): a hash of the user attributes (same as for user creation)
164 1 Jean-Philippe Lang
165 7 Jean-Philippe Lang
h3. DELETE
166 20 Cyril Jouve
167 20 Cyril Jouve
This endpoint requires admin privileges.
168 1 Jean-Philippe Lang
169 7 Jean-Philippe Lang
Deletes a user.
170 4 Jean-Philippe Lang
171 7 Jean-Philippe Lang
+Example+:
172 1 Jean-Philippe Lang
173 7 Jean-Philippe Lang
  DELETE /users/20.xml
174 1 Jean-Philippe Lang
175 1 Jean-Philippe Lang
+Response+:
176 4 Jean-Philippe Lang
177 4 Jean-Philippe Lang
  * @200 OK@: user was deleted
178 7 Jean-Philippe Lang
179 7 Jean-Philippe Lang
h2. See also
180 7 Jean-Philippe Lang
181 7 Jean-Philippe Lang
* The [[Rest_Memberships|Memberships API]] for adding or removing a user from a project.
182 7 Jean-Philippe Lang
* The [[Rest_Groups|Groups API]] for adding or removing a user from a group.