Project

General

Profile

Rest Users » History » Version 19

F. P., 2017-05-15 11:26
Added generate_password; fixed position of "send_information"

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