diff options
Diffstat (limited to 'doc/api/users.md')
| -rw-r--r-- | doc/api/users.md | 114 |
1 files changed, 50 insertions, 64 deletions
diff --git a/doc/api/users.md b/doc/api/users.md index c185cf6478a..94af37629ff 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -3,6 +3,7 @@ ## List users Get a list of users. + This function takes pagination parameters `page` and `per_page` to restrict the list of users. ``` @@ -53,8 +54,7 @@ GET /users ] ``` -You can search for a users by email or username with: -`/users?search=John` +You can search for a users by email or username with: `/users?search=John` Also see `def search query` in `app/models/user.rb`. @@ -68,7 +68,7 @@ GET /users/:id Parameters: -+ `id` (required) - The ID of a user +- `id` (required) - The ID of a user ```json { @@ -93,7 +93,6 @@ Parameters: } ``` - ## User creation Creates a new user. Note only administrators can create new users. @@ -104,21 +103,20 @@ POST /users Parameters: -+ `email` (required) - Email -+ `password` (required) - Password -+ `username` (required) - Username -+ `name` (required) - Name -+ `skype` (optional) - Skype ID -+ `linkedin` (optional) - Linkedin -+ `twitter` (optional) - Twitter account -+ `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 -+ `admin` (optional) - User is admin - true or false (default) -+ `can_create_group` (optional) - User can create groups - true or false - +- `email` (required) - Email +- `password` (required) - Password +- `username` (required) - Username +- `name` (required) - Name +- `skype` (optional) - Skype ID +- `linkedin` (optional) - Linkedin +- `twitter` (optional) - Twitter account +- `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 +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false ## User modification @@ -130,30 +128,26 @@ 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 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. ## 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 @@ -161,8 +155,7 @@ DELETE /users/:id Parameters: -+ `id` (required) - The ID of the user - +- `id` (required) - The ID of the user ## Current user @@ -194,7 +187,6 @@ GET /user } ``` - ## List SSH keys Get a list of currently authenticated user's SSH keys. @@ -220,7 +212,7 @@ GET /user/keys Parameters: -+ **none** +- **none** ## List SSH keys for user @@ -232,8 +224,7 @@ GET /users/:uid/keys Parameters: -+ `uid` (required) - id of specified user - +- `uid` (required) - id of specified user ## Single SSH key @@ -245,7 +236,7 @@ GET /user/keys/:id Parameters: -+ `id` (required) - The ID of an SSH key +- `id` (required) - The ID of an SSH key ```json { @@ -255,7 +246,6 @@ Parameters: } ``` - ## Add SSH key Creates a new key owned by the currently authenticated user. @@ -266,9 +256,8 @@ POST /user/keys Parameters: -+ `title` (required) - new SSH Key's title -+ `key` (required) - new SSH key - +- `title` (required) - new SSH Key's title +- `key` (required) - new SSH key ## Add SSH key for user @@ -280,17 +269,15 @@ POST /users/:id/keys Parameters: -+ `id` (required) - id of specified user -+ `title` (required) - new SSH Key's title -+ `key` (required) - new SSH key +- `id` (required) - id of specified user +- `title` (required) - new SSH Key's title +- `key` (required) - new SSH key -Will return created key with status `201 Created` on success, or `404 Not -found` on fail. +Will return created key with status `201 Created` on success, or `404 Not found` on fail. -## Delete SSH key +## 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 @@ -298,9 +285,9 @@ DELETE /user/keys/:id Parameters: -+ `id` (required) - SSH key ID +- `id` (required) - SSH key ID -## Delete SSH key +## Delete SSH key for given user Deletes key owned by a specified user. Available only for admin. @@ -310,8 +297,7 @@ DELETE /users/:uid/keys/:id Parameters: -+ `uid` (required) - id of specified user -+ `id` (required) - SSH key ID +- `uid` (required) - id of specified user +- `id` (required) - SSH key ID Will return `200 Ok` on success, or `404 Not found` if either user or key cannot be found. - |