BigW Consortium Gitlab

users.md 7.58 KB
Newer Older
1 2
# Users

3 4 5
## List users

Get a list of users.
6

7
This function takes pagination parameters `page` and `per_page` to restrict the list of users.
8

Ciro Santilli committed
9
### For normal users
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

```
GET /users
```

```json
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
  }
]
```

Ciro Santilli committed
34
### For admins
35

36 37 38 39 40 41 42 43
```
GET /users
```

```json
[
  {
    "id": 1,
44
    "username": "john_smith",
45 46
    "email": "john@example.com",
    "name": "John Smith",
47
    "state": "active",
48 49 50 51 52
    "created_at": "2012-05-23T08:00:58Z",
    "bio": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert committed
53
    "website_url": "",
54 55
    "extern_uid": "john.smith",
    "provider": "provider_name",
56
    "theme_id": 1,
57 58
    "color_scheme_id": 2,
    "is_admin": false,
59
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
60
    "can_create_group": true
61 62 63
  },
  {
    "id": 2,
64
    "username": "jack_smith",
65 66
    "email": "jack@example.com",
    "name": "Jack Smith",
67
    "state": "blocked",
68 69 70 71 72
    "created_at": "2012-05-23T08:01:01Z",
    "bio": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
Jerome Dalbert committed
73
    "website_url": "",
74 75
    "extern_uid": "jack.smith",
    "provider": "provider_name",
76
    "theme_id": 1,
77 78
    "color_scheme_id": 3,
    "is_admin": false,
79
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
80 81
    "can_create_group": true,
    "can_create_project": true
82 83 84 85
  }
]
```

Ciro Santilli committed
86
You can search for users by email or username with: `/users?search=John`
dosire committed
87 88

Also see `def search query` in `app/models/user.rb`.
89

90 91 92 93
## Single user

Get a single user.

Ciro Santilli committed
94
### For user
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113

```
GET /users/:id
```

Parameters:

- `id` (required) - The ID of a user

```json
{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
}
```

Ciro Santilli committed
114
### For admin
115

116 117 118 119 120 121
```
GET /users/:id
```

Parameters:

122
- `id` (required) - The ID of a user
123 124 125 126

```json
{
  "id": 1,
127
  "username": "john_smith",
128 129
  "email": "john@example.com",
  "name": "John Smith",
130
  "state": "active",
131 132 133 134 135
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert committed
136
  "website_url": "",
137 138
  "extern_uid": "john.smith",
  "provider": "provider_name",
139
  "theme_id": 1,
140 141
  "color_scheme_id": 2,
  "is_admin": false,
142 143
  "can_create_group": true,
  "can_create_project": true
144 145 146
}
```

147
## User creation
148 149

Creates a new user. Note only administrators can create new users.
150 151 152 153 154 155 156

```
POST /users
```

Parameters:

157 158 159 160 161
- `email` (required)            - Email
- `password` (required)         - Password
- `username` (required)         - Username
- `name` (required)             - Name
- `skype` (optional)            - Skype ID
Ciro Santilli committed
162
- `linkedin` (optional)         - LinkedIn
163
- `twitter` (optional)          - Twitter account
Ciro Santilli committed
164
- `website_url` (optional)      - Website URL
165 166 167
- `projects_limit` (optional)   - Number of projects user can create
- `extern_uid` (optional)       - External UID
- `provider` (optional)         - External provider name
Ciro Santilli committed
168
- `bio` (optional)              - User's biography
169 170
- `admin` (optional)            - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
171

172
## User modification
173 174

Modifies an existing user. Only administrators can change attributes of a user.
175 176 177 178 179 180

```
PUT /users/:id
```

Parameters:
181

Ciro Santilli committed
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
- `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.
200 201

## User deletion
202

Ciro Santilli committed
203 204
Deletes a user. Available only for administrators.
This is an idempotent function, calling this function for a non-existent user id
205
still returns a status code `200 OK`.
Ciro Santilli committed
206 207
The JSON response differs if the user was actually deleted or not.
In the former the user is returned and in the latter not.
208 209 210 211 212

```
DELETE /users/:id
```

213 214
Parameters:

215
- `id` (required) - The ID of the user
216

217 218
## Current user

219
Gets currently authenticated user.
220 221 222 223 224 225 226 227

```
GET /user
```

```json
{
  "id": 1,
228
  "username": "john_smith",
229 230
  "email": "john@example.com",
  "name": "John Smith",
Alex Denisov committed
231
  "private_token": "dd34asd13as",
232
  "state": "active",
233 234 235 236 237
  "created_at": "2012-05-23T08:00:58Z",
  "bio": null,
  "skype": "",
  "linkedin": "",
  "twitter": "",
Jerome Dalbert committed
238
  "website_url": "",
239 240
  "theme_id": 1,
  "color_scheme_id": 2,
Alex Denisov committed
241
  "is_admin": false,
242 243
  "can_create_group": true,
  "can_create_project": true
244 245
}
```
246 247 248 249 250 251 252 253 254 255 256 257 258

## List SSH keys

Get a list of currently authenticated user's SSH keys.

```
GET /user/keys
```

```json
[
  {
    "id": 1,
259 260
    "title": "Public key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
261 262 263
  },
  {
    "id": 3,
264 265
    "title": "Another Public key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
266 267 268 269
  }
]
```

270 271
Parameters:

272
- **none**
273

274 275 276 277 278 279 280 281 282 283
## List SSH keys for user

Get a list of a specified user's SSH keys. Available only for admin

```
GET /users/:uid/keys
```

Parameters:

284
- `uid` (required) - id of specified user
285

286 287 288 289 290 291 292 293 294 295
## Single SSH key

Get a single key.

```
GET /user/keys/:id
```

Parameters:

296
- `id` (required) - The ID of an SSH key
297 298 299 300

```json
{
  "id": 1,
301 302
  "title": "Public key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
303 304
}
```
305

306 307
## Add SSH key

308
Creates a new key owned by the currently authenticated user.
309 310 311 312 313 314 315

```
POST /user/keys
```

Parameters:

316
- `title` (required) - new SSH Key's title
Ciro Santilli committed
317
- `key` (required)   - new SSH key
318

319 320 321 322 323 324 325 326 327 328
## Add SSH key for user

Create new key owned by specified user. Available only for admin

```
POST /users/:id/keys
```

Parameters:

Ciro Santilli committed
329
- `id` (required)    - id of specified user
330
- `title` (required) - new SSH Key's title
Ciro Santilli committed
331
- `key` (required)   - new SSH key
332

333
Will return created key with status `201 Created` on success, or `404 Not found` on fail.
334

335
## Delete SSH key for current user
336

Ciro Santilli committed
337 338
Deletes key owned by currently authenticated user.
This is an idempotent function and calling it on a key that is already deleted
339
or not available results in `200 OK`.
340 341 342 343 344 345 346

```
DELETE /user/keys/:id
```

Parameters:

347
- `id` (required) - SSH key ID
348

349
## Delete SSH key for given user
350 351 352 353 354 355 356 357 358

Deletes key owned by a specified user. Available only for admin.

```
DELETE /users/:uid/keys/:id
```

Parameters:

359
- `uid` (required) - id of specified user
Ciro Santilli committed
360
- `id` (required)  - SSH key ID
361

362
Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.