Rest Users » History » Version 11

Jean-Baptiste Barth, 2013-05-06 22:49

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