User routes

This page describes both the /users and /users/:name routes.

Get user info

Requires authorization. Has an ACE.

Send a GET request to /users/:name.

Responses

Status	Comment
200 OK
404 Not Found	No such user.

Request	Response
GET /users/nickname HTTP/1.1 Cookie: ... ...	HTTP/1.1 200 OK ... {"success": true, "code": 200, "data": {"nickname": "nickname", "groups": ["group1", "group2"]}, ... }
GET /users/no-such-nickname HTTP/1.1 Cookie: ... ...	HTTP/1.1 404 Not Found ... {"success": false, "code": 400, ... }

Delete a user

Requires authorization.

Send a DELETE request to /users/:name.

Responses

Status	Comment
201 No Content	User deleted successfully.
404 Not Found

Request	Response
DELETE /users/nickname Cookie: ... ...	HTTP/1.1 201 No Content ...
DELETE /users/no-such-user HTTP/1.1 Cookie: ... ...	HTTP/1.1 404 Not Found ...

Update a user

Requires authorization. Has an ACE.

Send a PATCH request to /users/:name. The body should contain fields to update.

Body

Field name	Admin-only	Comment
nickname	Yes	User nickname.
groups	Yes	User groups.
password	No	User password (will be hashed and stored).

Responses

Status	Comment
204 No Content	Successfully updated.
400 Bad Request	The provided data is malformed.
404 Not Found
403 Forbidden	Tried to update admin-only fields without admin permissions.

Request	Response
PATCH /users/nickname HTTP/1.1 Cookie: ... ... {"nickname": "new-nick", "groups": ["new-group"]}	HTTP/1.1 204 No Content ...
PATCH /users/nickname HTTP/1.1 Cookie: ... ... {"nickname": ""}	HTTP/1.1 400 Bad Request ... {"success": false, "code": 400, ... }
PATCH /users/no-such-user HTTP/1.1 Cookie: ... ... {}	HTTP/1.1 404 Not Found ... {"success": false, "code": 404, ... }

List users

Send a GET request to /users. The query parameters are:

Name	Type	Comment
offset	integer, optional	Zero-based offset from the beginning of the list.
groups	strings	User list is filtered by the provided list of groups.

Responses

Status	Comment
200 OK

Request	Response
GET /users HTTP/1.1 ...	HTTP/1.1 200 OK ... {"success": true, "code": 200, "data": { "offset": 0, "total": 150, "sent": 20, "truncated": true, "list": [ {"nickname": "user-1", "groups": [...]}, ... ] }, ... }
GET /users?offset=10&groups=group-1&groups=group2 HTTP/1.1 ...	HTTP/1.1 200 OK ... {"success": true, "code": 200, "data": { "offset": 10, "sent": 20, "total": 150, "truncated": true, "list": [ {"nickname": "user-123", "groups": ["group-1", "group-2", ...]}, ... ] }, ... }

Changes

Version	Changes
3.2.0	User password can be changed now.
3.1.0	Wrapped the user update code. Views check for JSON validity and user existence.
3.0.0	Added metadata to the result of Users:GET.