Rest Users » History » Version 21
Cyril Jouve, 2017-08-30 12:14
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 | 21 | 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 (see Response below). |
92 | 20 | Cyril Jouve | |
93 | 3 | Jean-Philippe Lang | +Parameters+: |
94 | 1 | Jean-Philippe Lang | |
95 | 1 | Jean-Philippe Lang | * @include@ (optional): a coma separated list of associations to include in the response: |
96 | 1 | Jean-Philippe Lang | |
97 | 11 | Jean-Baptiste Barth | * @memberships@ : adds extra information about user's memberships and roles on the projects |
98 | 11 | Jean-Baptiste Barth | * @groups@ (added in 2.1) : adds extra information about user's groups |
99 | 1 | Jean-Philippe Lang | |
100 | 7 | Jean-Philippe Lang | +Examples+: |
101 | 1 | Jean-Philippe Lang | |
102 | 7 | Jean-Philippe Lang | GET /users/current.xml |
103 | 7 | Jean-Philippe Lang | |
104 | 7 | Jean-Philippe Lang | Returns the details about the current user. |
105 | 7 | Jean-Philippe Lang | |
106 | 1 | Jean-Philippe Lang | GET /users/3.xml?include=memberships,groups |
107 | 1 | Jean-Philippe Lang | |
108 | 1 | Jean-Philippe Lang | Returns the details about user ID 3, and additional detail about the user's project memberships. |
109 | 1 | Jean-Philippe Lang | |
110 | 18 | Toshi MARUYAMA | +Response+: |
111 | 1 | Jean-Philippe Lang | |
112 | 18 | Toshi MARUYAMA | <pre><code class="xml"> |
113 | 1 | Jean-Philippe Lang | <user> |
114 | 1 | Jean-Philippe Lang | <id>3</id> |
115 | 1 | Jean-Philippe Lang | <login>jplang</login> |
116 | 1 | Jean-Philippe Lang | <firstname>Jean-Philippe</firstname> |
117 | 1 | Jean-Philippe Lang | <lastname>Lang</lastname> |
118 | 1 | Jean-Philippe Lang | <mail>jp_lang@yahoo.fr</mail> |
119 | 1 | Jean-Philippe Lang | <created_on>2007-09-28T00:16:04+02:00</created_on> |
120 | 1 | Jean-Philippe Lang | <last_login_on>2011-08-01T18:05:45+02:00</last_login_on> |
121 | 14 | Go MAEDA | <api_key>ebc3f6b781a6fb3f2b0a83ce0ebb80e0d585189d</api_key> |
122 | 14 | Go MAEDA | <status>1</status> |
123 | 5 | Rick Mason | <custom_fields type="array" /> |
124 | 1 | Jean-Philippe Lang | <memberships type="array"> |
125 | 4 | Jean-Philippe Lang | <membership> |
126 | 4 | Jean-Philippe Lang | <project name="Redmine" id="1"/> |
127 | 4 | Jean-Philippe Lang | <roles type="array"> |
128 | 4 | Jean-Philippe Lang | <role name="Administrator" id="3"/> |
129 | 4 | Jean-Philippe Lang | <role name="Contributor" id="4"/> |
130 | 1 | Jean-Philippe Lang | </roles> |
131 | 1 | Jean-Philippe Lang | </membership> |
132 | 1 | Jean-Philippe Lang | </memberships> |
133 | 1 | Jean-Philippe Lang | <groups type="array"> |
134 | 1 | Jean-Philippe Lang | <group id="20" name="Developers"/> |
135 | 1 | Jean-Philippe Lang | </groups> |
136 | 1 | Jean-Philippe Lang | </user> |
137 | 1 | Jean-Philippe Lang | </code></pre> |
138 | 4 | Jean-Philippe Lang | |
139 | 21 | Cyril Jouve | If the user doing the request is not admin, it depends on the requested user: |
140 | 21 | Cyril Jouve | |
141 | 21 | 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 |
142 | 21 | 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 |
143 | 21 | Cyril Jouve | * if the user is locked, the endpoint returns 404 status code |
144 | 21 | Cyril Jouve | |
145 | 21 | Cyril Jouve | If the user doing the request is admin, a user object is always returned (blocked or not). It will have some more details: |
146 | 9 | Jean-Baptiste Barth | * @api_key@ : the API key of the user, visible for admins and for yourself (added in 2.3.0) |
147 | 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. |
148 | 9 | Jean-Baptiste Barth | |
149 | 7 | Jean-Philippe Lang | h3. PUT |
150 | 4 | Jean-Philippe Lang | |
151 | 7 | Jean-Philippe Lang | Updates a user. |
152 | 4 | Jean-Philippe Lang | |
153 | 20 | Cyril Jouve | This endpoint requires admin privileges. |
154 | 20 | Cyril Jouve | |
155 | 1 | Jean-Philippe Lang | +Example+: |
156 | 1 | Jean-Philippe Lang | |
157 | 7 | Jean-Philippe Lang | PUT /users/20.xml |
158 | 1 | Jean-Philippe Lang | |
159 | 1 | Jean-Philippe Lang | +Parameters+: |
160 | 1 | Jean-Philippe Lang | |
161 | 1 | Jean-Philippe Lang | * @user@ (required): a hash of the user attributes (same as for user creation) |
162 | 1 | Jean-Philippe Lang | |
163 | 7 | Jean-Philippe Lang | h3. DELETE |
164 | 20 | Cyril Jouve | |
165 | 20 | Cyril Jouve | This endpoint requires admin privileges. |
166 | 1 | Jean-Philippe Lang | |
167 | 7 | Jean-Philippe Lang | Deletes a user. |
168 | 4 | Jean-Philippe Lang | |
169 | 7 | Jean-Philippe Lang | +Example+: |
170 | 1 | Jean-Philippe Lang | |
171 | 7 | Jean-Philippe Lang | DELETE /users/20.xml |
172 | 1 | Jean-Philippe Lang | |
173 | 1 | Jean-Philippe Lang | +Response+: |
174 | 4 | Jean-Philippe Lang | |
175 | 4 | Jean-Philippe Lang | * @200 OK@: user was deleted |
176 | 7 | Jean-Philippe Lang | |
177 | 7 | Jean-Philippe Lang | h2. See also |
178 | 7 | Jean-Philippe Lang | |
179 | 7 | Jean-Philippe Lang | * The [[Rest_Memberships|Memberships API]] for adding or removing a user from a project. |
180 | 7 | Jean-Philippe Lang | * The [[Rest_Groups|Groups API]] for adding or removing a user from a group. |