Project

General

Profile

Rest Users » History » Version 9

Jean-Baptiste Barth, 2013-05-05 10:30
Add some info for /users/:id (see #13155 and #13948)

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