Rest Users » History » Revision 11
« Previous |
Revision 11/30
(diff)
| Next »
Jean-Baptiste Barth, 2013-05-06 22:49
Users¶
- Table of contents
- Users
/users.:format¶
GET¶
Returns a list of users.
Example:
GET /users.xml
Optional filters:
status
: get only users with the given status. See app/models/principal.rb for a list of available statuses. Default is1
(active users)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.group_id
: get only users who are members of the given group
POST¶
Creates a user.
Parameters:
user
(required): a hash of the user attributes, including:login
(required): the user loginpassword
: the user passwordfirstname
(required)lastname
(required)mail
(required)auth_source_id
: authentication mode id
Example:
POST /users.xml <?xml version="1.0" encoding="ISO-8859-1" ?> <user> <login>jplang</login> <firstname>Jean-Philippe</firstname> <lastname>Lang</lastname> <password>secret</password> <mail>jp_lang@yahoo.fr</mail> <auth_source_id>2</auth_source_id> </user>
JSON
{ "user": { "login": "jplang", "firstname": "Jean-Philippe", "lastname": "Lang", "mail": "jp_lang@yahoo.fr", "password": "secret" } }
Response:
201 Created
: user was created422 Unprocessable Entity
: user was not created due to validation failures (response body contains the error messages)
/users/:id.:format¶
GET¶
Returns the user details. You can use /users/current.:format
for retrieving the user whose credentials are used to access the API.
Parameters:
include
(optional): a coma separated list of associations to include in the response:memberships
: adds extra information about user's memberships and roles on the projectsgroups
(added in 2.1) : adds extra information about user's groups
Examples:
GET /users/current.xml
Returns the details about the current user.
GET /users/3.xml?include=memberships,groups
Returns the details about user ID 3, and additional detail about the user's project memberships.
Reponse:
<user> <id>3</id> <login>jplang</login> <firstname>Jean-Philippe</firstname> <lastname>Lang</lastname> <mail>jp_lang@yahoo.fr</mail> <created_on>2007-09-28T00:16:04+02:00</created_on> <last_login_on>2011-08-01T18:05:45+02:00</last_login_on> <custom_fields type="array" /> <memberships type="array"> <membership> <project name="Redmine" id="1"/> <roles type="array"> <role name="Administrator" id="3"/> <role name="Contributor" id="4"/> </roles> </membership> </memberships> <groups type="array"> <group id="20" name="Developers"/> </groups> </user>Depending on the status of the user who makes the request, you can get some more details:
api_key
: the API key of the user, visible for admins and for yourself (added in 2.3.0)status
: a numeric id representing the status of the user, visible for admins only (added in 2.4.0). See app/models/principal.rb for a list of available statuses.
PUT¶
Updates a user.
Example:
PUT /users/20.xml
Parameters:
user
(required): a hash of the user attributes (same as for user creation)
DELETE¶
Deletes a user.
Example:
DELETE /users/20.xml
Response:
200 OK
: user was deleted
See also¶
- The Memberships API for adding or removing a user from a project.
- The Groups API for adding or removing a user from a group.
Updated by Jean-Baptiste Barth over 11 years ago · 11 revisions