Rest Users » History » Version 12
Matt Wiseley, 2014-12-13 18:12
Added 2 extra supported fieldsthat I had to look up in source code (mail_notification, must_change_passwd)
1 | 1 | Jean-Philippe Lang | h1. Users |
---|---|---|---|
2 | |||
3 | 3 | Jean-Philippe Lang | {{>toc}} |
4 | |||
5 | 7 | Jean-Philippe Lang | h2. /users.:format |
6 | 1 | Jean-Philippe Lang | |
7 | 7 | Jean-Philippe Lang | h3. GET |
8 | |||
9 | Returns a list of users. |
||
10 | |||
11 | +Example+: |
||
12 | |||
13 | 1 | Jean-Philippe Lang | GET /users.xml |
14 | |||
15 | 10 | Jean-Baptiste Barth | Optional filters: |
16 | |||
17 | * @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) |
||
18 | * @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. |
||
19 | * @group_id@: get only users who are members of the given group |
||
20 | |||
21 | 7 | Jean-Philippe Lang | h3. POST |
22 | 1 | Jean-Philippe Lang | |
23 | 7 | Jean-Philippe Lang | Creates a user. |
24 | 1 | Jean-Philippe Lang | |
25 | 7 | Jean-Philippe Lang | +Parameters+: |
26 | 1 | Jean-Philippe Lang | |
27 | 7 | Jean-Philippe Lang | * @user@ (required): a hash of the user attributes, including: |
28 | 1 | Jean-Philippe Lang | |
29 | 7 | Jean-Philippe Lang | * @login@ (required): the user login |
30 | * @password@: the user password |
||
31 | * @firstname@ (required) |
||
32 | * @lastname@ (required) |
||
33 | * @mail@ (required) |
||
34 | * @auth_source_id@: authentication mode id |
||
35 | 12 | Matt Wiseley | * @mail_notification@: only_my_events, none, etc. |
36 | * @must_change_passwd@: true or false |
||
37 | |||
38 | 1 | Jean-Philippe Lang | |
39 | 7 | Jean-Philippe Lang | +Example+: |
40 | 1 | Jean-Philippe Lang | |
41 | 7 | Jean-Philippe Lang | <pre> |
42 | POST /users.xml |
||
43 | |||
44 | <?xml version="1.0" encoding="ISO-8859-1" ?> |
||
45 | <user> |
||
46 | <login>jplang</login> |
||
47 | <firstname>Jean-Philippe</firstname> |
||
48 | <lastname>Lang</lastname> |
||
49 | <password>secret</password> |
||
50 | <mail>jp_lang@yahoo.fr</mail> |
||
51 | <auth_source_id>2</auth_source_id> |
||
52 | </user> |
||
53 | </pre> |
||
54 | |||
55 | 8 | Lutz Horn | JSON |
56 | |||
57 | <pre> |
||
58 | { |
||
59 | "user": { |
||
60 | "login": "jplang", |
||
61 | "firstname": "Jean-Philippe", |
||
62 | "lastname": "Lang", |
||
63 | "mail": "jp_lang@yahoo.fr", |
||
64 | "password": "secret" |
||
65 | } |
||
66 | } |
||
67 | </pre> |
||
68 | |||
69 | 7 | Jean-Philippe Lang | +Response+: |
70 | |||
71 | * @201 Created@: user was created |
||
72 | * @422 Unprocessable Entity@: user was not created due to validation failures (response body contains the error messages) |
||
73 | |||
74 | h2. /users/:id.:format |
||
75 | |||
76 | h3. GET |
||
77 | |||
78 | Returns the user details. You can use @/users/current.:format@ for retrieving the user whose credentials are used to access the API. |
||
79 | |||
80 | 3 | Jean-Philippe Lang | +Parameters+: |
81 | 1 | Jean-Philippe Lang | |
82 | * @include@ (optional): a coma separated list of associations to include in the response: |
||
83 | |||
84 | 11 | Jean-Baptiste Barth | * @memberships@ : adds extra information about user's memberships and roles on the projects |
85 | * @groups@ (added in 2.1) : adds extra information about user's groups |
||
86 | 1 | Jean-Philippe Lang | |
87 | 7 | Jean-Philippe Lang | +Examples+: |
88 | 1 | Jean-Philippe Lang | |
89 | 7 | Jean-Philippe Lang | GET /users/current.xml |
90 | |||
91 | Returns the details about the current user. |
||
92 | |||
93 | 1 | Jean-Philippe Lang | GET /users/3.xml?include=memberships,groups |
94 | |||
95 | Returns the details about user ID 3, and additional detail about the user's project memberships. |
||
96 | |||
97 | +Reponse+: |
||
98 | |||
99 | <pre> |
||
100 | <user> |
||
101 | <id>3</id> |
||
102 | <login>jplang</login> |
||
103 | <firstname>Jean-Philippe</firstname> |
||
104 | <lastname>Lang</lastname> |
||
105 | <mail>jp_lang@yahoo.fr</mail> |
||
106 | <created_on>2007-09-28T00:16:04+02:00</created_on> |
||
107 | <last_login_on>2011-08-01T18:05:45+02:00</last_login_on> |
||
108 | 5 | Rick Mason | <custom_fields type="array" /> |
109 | 1 | Jean-Philippe Lang | <memberships type="array"> |
110 | 4 | Jean-Philippe Lang | <membership> |
111 | <project name="Redmine" id="1"/> |
||
112 | <roles type="array"> |
||
113 | <role name="Administrator" id="3"/> |
||
114 | <role name="Contributor" id="4"/> |
||
115 | 1 | Jean-Philippe Lang | </roles> |
116 | </membership> |
||
117 | 4 | Jean-Philippe Lang | </memberships> |
118 | <groups type="array"> |
||
119 | <group id="20" name="Developers"/> |
||
120 | </groups> |
||
121 | </user> |
||
122 | </pre> |
||
123 | |||
124 | 9 | Jean-Baptiste Barth | Depending on the status of the user who makes the request, you can get some more details: |
125 | * @api_key@ : the API key of the user, visible for admins and for yourself (added in 2.3.0) |
||
126 | * @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. |
||
127 | |||
128 | 7 | Jean-Philippe Lang | h3. PUT |
129 | 4 | Jean-Philippe Lang | |
130 | 7 | Jean-Philippe Lang | Updates a user. |
131 | 4 | Jean-Philippe Lang | |
132 | 1 | Jean-Philippe Lang | +Example+: |
133 | |||
134 | 7 | Jean-Philippe Lang | PUT /users/20.xml |
135 | 1 | Jean-Philippe Lang | |
136 | +Parameters+: |
||
137 | |||
138 | * @user@ (required): a hash of the user attributes (same as for user creation) |
||
139 | |||
140 | 7 | Jean-Philippe Lang | h3. DELETE |
141 | 1 | Jean-Philippe Lang | |
142 | 7 | Jean-Philippe Lang | Deletes a user. |
143 | 4 | Jean-Philippe Lang | |
144 | 7 | Jean-Philippe Lang | +Example+: |
145 | 1 | Jean-Philippe Lang | |
146 | 7 | Jean-Philippe Lang | DELETE /users/20.xml |
147 | 1 | Jean-Philippe Lang | |
148 | +Response+: |
||
149 | 4 | Jean-Philippe Lang | |
150 | * @200 OK@: user was deleted |
||
151 | 7 | Jean-Philippe Lang | |
152 | h2. See also |
||
153 | |||
154 | * The [[Rest_Memberships|Memberships API]] for adding or removing a user from a project. |
||
155 | * The [[Rest_Groups|Groups API]] for adding or removing a user from a group. |