diff --git a/doc/api/users.md b/doc/api/users.md index a7e9518408c2f6ef215b1c4128affa99e44678e5..57078353fd0d84007d591790f13bf4927c35f45a 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -6,7 +6,7 @@ Get a list of users. This function takes pagination parameters `page` and `per_page` to restrict the list of users. -### For normal users: +### For normal users ``` GET /users @@ -31,8 +31,7 @@ GET /users ] ``` - -### For admins: +### For admins ``` GET /users @@ -92,7 +91,7 @@ Also see `def search query` in `app/models/user.rb`. Get a single user. -#### For user: +### For user ``` GET /users/:id @@ -112,8 +111,7 @@ Parameters: } ``` - -#### For admin: +### For admin ``` GET /users/:id @@ -161,13 +159,13 @@ Parameters: - `username` (required) - Username - `name` (required) - Name - `skype` (optional) - Skype ID -- `linkedin` (optional) - Linkedin +- `linkedin` (optional) - LinkedIn - `twitter` (optional) - Twitter account -- `website_url` (optional) - Website url +- `website_url` (optional) - Website URL - `projects_limit` (optional) - Number of projects user can create - `extern_uid` (optional) - External UID - `provider` (optional) - External provider name -- `bio` (optional) - User's bio +- `bio` (optional) - User's biography - `admin` (optional) - User is admin - true or false (default) - `can_create_group` (optional) - User can create groups - true or false @@ -181,26 +179,32 @@ PUT /users/:id Parameters: -- `email` - Email -- `username` - Username -- `name` - Name -- `password` - Password -- `skype` - Skype ID -- `linkedin` - Linkedin -- `twitter` - Twitter account -- `website_url` - Website url -- `projects_limit` - Limit projects each user can create -- `extern_uid` - External UID -- `provider` - External provider name -- `bio` - User's bio -- `admin` (optional) - User is admin - true or false (default) -- `can_create_group` (optional) - User can create groups - true or false - -Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one. +- `email` - Email +- `username` - Username +- `name` - Name +- `password` - Password +- `skype` - Skype ID +- `linkedin` - LinkedIn +- `twitter` - Twitter account +- `website_url` - Website URL +- `projects_limit` - Limit projects each user can create +- `extern_uid` - External UID +- `provider` - External provider name +- `bio` - User's biography +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false + +Note, at the moment this method does only return a 404 error, +even in cases where a 409 (Conflict) would be more appropriate, +e.g. when renaming the email address to some existing one. ## User deletion -Deletes a user. Available only for administrators. This is an idempotent function, calling this function for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user was actually deleted or not. In the former the user is returned and in the latter not. +Deletes a user. Available only for administrators. +This is an idempotent function, calling this function for a non-existent user id +still returns a status code `200 Ok`. +The JSON response differs if the user was actually deleted or not. +In the former the user is returned and in the latter not. ``` DELETE /users/:id @@ -310,7 +314,7 @@ POST /user/keys Parameters: - `title` (required) - new SSH Key's title -- `key` (required) - new SSH key +- `key` (required) - new SSH key ## Add SSH key for user @@ -322,15 +326,17 @@ POST /users/:id/keys Parameters: -- `id` (required) - id of specified user +- `id` (required) - id of specified user - `title` (required) - new SSH Key's title -- `key` (required) - new SSH key +- `key` (required) - new SSH key Will return created key with status `201 Created` on success, or `404 Not found` on fail. ## Delete SSH key for current user -Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already deleted or not available results in `200 Ok`. +Deletes key owned by currently authenticated user. +This is an idempotent function and calling it on a key that is already deleted +or not available results in `200 Ok`. ``` DELETE /user/keys/:id @@ -351,6 +357,6 @@ DELETE /users/:uid/keys/:id Parameters: - `uid` (required) - id of specified user -- `id` (required) - SSH key ID +- `id` (required) - SSH key ID Will return `200 Ok` on success, or `404 Not found` if either user or key cannot be found.