summaryrefslogtreecommitdiff
path: root/doc/api/users.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/users.md')
-rw-r--r--doc/api/users.md114
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.
-