Project

General

Profile

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.