projects.md 12.5 KB
Newer Older
1 2 3
## Projects

### List projects
Nihad Abbasov's avatar
Nihad Abbasov committed
4

5
Get a list of projects owned by the authenticated user.
Nihad Abbasov's avatar
Nihad Abbasov committed
6 7 8 9 10 11 12 13

```
GET /projects
```

```json
[
  {
Marin Jankovski's avatar
Marin Jankovski committed
14
    "id": 4,
Nihad Abbasov's avatar
Nihad Abbasov committed
15 16
    "description": null,
    "default_branch": "master",
Marin Jankovski's avatar
Marin Jankovski committed
17 18 19 20
    "public": false,
    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
    "web_url": "http://example.com/diaspora/diaspora-client",
Nihad Abbasov's avatar
Nihad Abbasov committed
21
    "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
22 23 24
      "id": 3,
      "name": "Diaspora",
      "created_at": "2013-09-30T13: 46: 02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
25
    },
Marin Jankovski's avatar
Marin Jankovski committed
26 27 28 29 30 31 32
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wall_enabled": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
33
    "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
34 35 36 37 38 39 40 41 42 43 44 45
    "snippets_enabled": false,
    "created_at": "2013-09-30T13: 46: 02Z",
    "last_activity_at": "2013-09-30T13: 46: 02Z",
    "namespace": {
      "created_at": "2013-09-30T13: 46: 02Z",
      "description": "",
      "id": 3,
      "name": "Diaspora",
      "owner_id": 1,
      "path": "diaspora",
      "updated_at": "2013-09-30T13: 46: 02Z"
    }
Nihad Abbasov's avatar
Nihad Abbasov committed
46 47
  },
  {
Marin Jankovski's avatar
Marin Jankovski committed
48
    "id": 6,
Nihad Abbasov's avatar
Nihad Abbasov committed
49
    "description": null,
Marin Jankovski's avatar
Marin Jankovski committed
50 51 52 53 54 55 56 57 58
    "default_branch": "master",
    "public": false,
    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
    "web_url": "http://example.com/brightbox/puppet",
    "owner":  {
      "id": 4,
      "name": "Brightbox",
      "created_at": "2013-09-30T13:46:02Z"
Nihad Abbasov's avatar
Nihad Abbasov committed
59
    },
Marin Jankovski's avatar
Marin Jankovski committed
60 61 62 63
    "name": "Puppet",
    "name_with_namespace": "Brightbox / Puppet",
    "path": "puppet",
    "path_with_namespace": "brightbox/puppet",
Nihad Abbasov's avatar
Nihad Abbasov committed
64 65
    "issues_enabled": true,
    "merge_requests_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
66
    "wall_enabled": false,
Nihad Abbasov's avatar
Nihad Abbasov committed
67
    "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
68 69 70 71 72 73 74 75 76 77 78 79
    "snippets_enabled": false,
    "created_at": "2013-09-30T13:46:02Z",
    "last_activity_at": "2013-09-30T13:46:02Z",
    "namespace":  {
      "created_at": "2013-09-30T13:46:02Z",
      "description": "",
      "id": 4,
      "name": "Brightbox",
      "owner_id": 1,
      "path": "brightbox",
      "updated_at": "2013-09-30T13:46:02Z"
    }
Nihad Abbasov's avatar
Nihad Abbasov committed
80 81 82 83
  }
]
```

84 85

### Get single project
Nihad Abbasov's avatar
Nihad Abbasov committed
86

Marin Jankovski's avatar
Marin Jankovski committed
87 88
Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME , which is owned by the authentication user.
If using namespaced projects call make sure that the NAMESPACE/PROJECT_NAME is URL-encoded, eg. `/api/v3/projects/diaspora%2Fdiaspora` (where `/` is represented by `%2F`).
Nihad Abbasov's avatar
Nihad Abbasov committed
89 90 91 92 93 94 95

```
GET /projects/:id
```

Parameters:

Marin Jankovski's avatar
Marin Jankovski committed
96
+ `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project
Nihad Abbasov's avatar
Nihad Abbasov committed
97

98 99
```json
{
Marin Jankovski's avatar
Marin Jankovski committed
100
  "id": 3,
101
  "description": null,
Marin Jankovski's avatar
Marin Jankovski committed
102 103 104 105 106
  "default_branch": "master",
  "public": false,
  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
  "web_url": "http://example.com/diaspora/diaspora-project-site",
107
  "owner": {
Marin Jankovski's avatar
Marin Jankovski committed
108 109 110
    "id": 3,
    "name": "Diaspora",
    "created_at": "2013-09-30T13: 46: 02Z"
111
  },
Marin Jankovski's avatar
Marin Jankovski committed
112 113 114 115
  "name": "Diaspora Project Site",
  "name_with_namespace": "Diaspora / Diaspora Project Site",
  "path": "diaspora-project-site",
  "path_with_namespace": "diaspora/diaspora-project-site",
116 117
  "issues_enabled": true,
  "merge_requests_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
118
  "wall_enabled": false,
119
  "wiki_enabled": true,
Marin Jankovski's avatar
Marin Jankovski committed
120 121 122 123 124 125 126 127 128 129 130 131
  "snippets_enabled": false,
  "created_at": "2013-09-30T13: 46: 02Z",
  "last_activity_at": "2013-09-30T13: 46: 02Z",
  "namespace": {
    "created_at": "2013-09-30T13: 46: 02Z",
    "description": "",
    "id": 3,
    "name": "Diaspora",
    "owner_id": 1,
    "path": "diaspora",
    "updated_at": "2013-09-30T13: 46: 02Z"
  }
132 133 134
}
```

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
### Get project events

Get a project events for specific project.
Sorted from newest to latest

```
GET /projects/:id/events
```

Parameters:

+ `id` (required) - The ID or NAME of a project

```json

[{
  "title": null,
  "project_id": 15,
  "action_name": "closed",
  "target_id": 830,
  "target_type": "Issue",
  "author_id": 1,
  "data": null,
  "target_title": "Public project search field"
}, {
  "title": null,
  "project_id": 15,
  "action_name": "opened",
  "target_id": null,
  "target_type": null,
  "author_id": 1,
  "data": {
    "before": "50d4420237a9de7be1304607147aec22e4a14af7",
    "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
    "ref": "refs/heads/master",
    "user_id": 1,
    "user_name": "Dmitriy Zaporozhets",
    "repository": {
      "name": "gitlabhq",
      "url": "git@dev.gitlab.org:gitlab/gitlabhq.git",
      "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.",
      "homepage": "https://dev.gitlab.org/gitlab/gitlabhq"
    },
    "commits": [{
      "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
      "message": "Add simple search to projects in public area",
      "timestamp": "2013-05-13T18:18:08+00:00",
      "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428",
      "author": {
        "name": "Dmitriy Zaporozhets",
        "email": "dmitriy.zaporozhets@gmail.com"
      }
    }],
    "total_commits_count": 1
  },
  "target_title": null
}, {
  "title": null,
  "project_id": 15,
  "action_name": "closed",
  "target_id": 840,
  "target_type": "Issue",
  "author_id": 1,
  "data": null,
  "target_title": "Finish & merge Code search PR"
}]
```

203 204

### Create project
205

206
Creates new project owned by user.
207 208 209 210 211 212 213 214

```
POST /projects
```

Parameters:

+ `name` (required) - new project name
215
+ `description` (optional) - short project description
216
+ `default_branch` (optional) - 'master' by default
217 218 219 220 221
+ `issues_enabled` (optional)
+ `wall_enabled` (optional)
+ `merge_requests_enabled` (optional)
+ `wiki_enabled` (optional) 
+ `snippets_enabled` (optional)
222
+ `public` (optional)
223

224

225 226 227
### Create project for user

Creates a new project owned by user. Available only for admins.
228 229 230 231 232 233 234 235 236 237 238

```
POST /projects/user/:user_id
```

Parameters:

+ `user_id` (required) - user_id of owner
+ `name` (required) - new project name
+ `description` (optional) - short project description
+ `default_branch` (optional) - 'master' by default
239 240 241 242 243
+ `issues_enabled` (optional)
+ `wall_enabled` (optional)
+ `merge_requests_enabled` (optional)
+ `wiki_enabled` (optional) 
+ `snippets_enabled` (optional)
244
+ `public` (optional)
245

246

247 248 249 250 251 252 253 254 255 256 257 258
## Remove project

Removes project with all resources(issues, merge requests etc)

```
DELETE /projects/:id
```

Parameters:

+ `id` (required) - The ID of a project

259 260 261 262

## Team members

### List project team members
miks's avatar
miks committed
263

264
Get a list of project team members.
miks's avatar
miks committed
265 266

```
267
GET /projects/:id/members
miks's avatar
miks committed
268 269 270 271
```

Parameters:

272
+ `id` (required) - The ID or NAME of a project
273
+ `query` (optional) - Query string to search for members
274 275 276


### Get project team member
miks's avatar
miks committed
277

278
Gets a project team member.
279

280 281 282 283 284
```
GET /projects/:id/members/:user_id
```

Parameters:
285

286
+ `id` (required) - The ID or NAME of a project
287 288 289 290 291
+ `user_id` (required) - The ID of a user

```json
{
  "id": 1,
292
  "username": "john_smith",
293 294
  "email": "john@example.com",
  "name": "John Smith",
Marin Jankovski's avatar
Marin Jankovski committed
295
  "state": "active",
296 297 298
  "created_at": "2012-05-23T08:00:58Z",
  "access_level": 40
}
299
```
300

301 302

### Add project team member
303

304 305
Adds a user to a project team. This is an idempotent method and can be called multiple times
with the same parameters. Adding team membership to a user that is already a member does not
306
affect the existing membership.
307 308 309

```
POST /projects/:id/members
310 311 312 313
```

Parameters:

314
+ `id` (required) - The ID or NAME of a project
315 316
+ `user_id` (required) - The ID of a user to add
+ `access_level` (required) - Project access level
317

318 319

### Edit project team member
miks's avatar
miks committed
320

321
Updates project team member to a specified access level.
miks's avatar
miks committed
322 323

```
324
PUT /projects/:id/members/:user_id
miks's avatar
miks committed
325 326 327 328
```

Parameters:

329
+ `id` (required) - The ID or NAME of a project
330 331
+ `user_id` (required) - The ID of a team member
+ `access_level` (required) - Project access level
miks's avatar
miks committed
332

333 334

### Remove project team member
miks's avatar
miks committed
335

336
Removes user from project team.
miks's avatar
miks committed
337 338

```
339
DELETE /projects/:id/members/:user_id
miks's avatar
miks committed
340 341 342 343
```

Parameters:

344
+ `id` (required) - The ID or NAME of a project
345
+ `user_id` (required) - The ID of a team member
miks's avatar
miks committed
346

347 348 349
This method is idempotent and can be called multiple times with the same parameters.
Revoking team membership for a user who is not currently a team member is considered success.
Please note that the returned JSON currently differs slightly. Thus you should not
350
rely on the returned JSON structure.
Nihad Abbasov's avatar
Nihad Abbasov committed
351

miks's avatar
miks committed
352

353 354 355 356 357
## Hooks

### List project hooks

Get list of project hooks.
miks's avatar
miks committed
358 359 360 361 362 363 364

```
GET /projects/:id/hooks
```

Parameters:

365
+ `id` (required) - The ID or NAME of a project
miks's avatar
miks committed
366 367


368
### Get project hook
369

370
Get a specific hook for project.
371 372 373 374 375

```
GET /projects/:id/hooks/:hook_id
```

376
Parameters:
377

378
+ `id` (required) - The ID or NAME of a project
379 380
+ `hook_id` (required) - The ID of a project hook

381 382 383 384 385 386 387 388
```json
{
  "id": 1,
  "url": "http://example.com/hook",
  "created_at": "2012-10-12T17:04:47Z"
}
```

miks's avatar
miks committed
389

390 391 392
### Add project hook

Adds a hook to project.
miks's avatar
miks committed
393 394 395 396 397 398 399

```
POST /projects/:id/hooks
```

Parameters:

400
+ `id` (required) - The ID or NAME of a project
miks's avatar
miks committed
401 402
+ `url` (required) - The hook URL

403

404 405 406
### Edit project hook

Edits a hook for project.
407 408 409 410 411 412 413

```
PUT /projects/:id/hooks/:hook_id
```

Parameters:

414
+ `id` (required) - The ID or NAME of a project
415 416 417 418
+ `hook_id` (required) - The ID of a project hook
+ `url` (required) - The hook URL


419
### Delete project hook
miks's avatar
miks committed
420

421 422
Removes a hook from project. This is an idempotent method and can be called multiple times.
Either the hook is available or not.
miks's avatar
miks committed
423 424

```
425
DELETE /projects/:id/hooks/:hook_id
miks's avatar
miks committed
426 427 428 429
```

Parameters:

430
+ `id` (required) - The ID or NAME of a project
miks's avatar
miks committed
431 432
+ `hook_id` (required) - The ID of hook to delete

433 434
Note the JSON response differs if the hook is available or not. If the project hook
is available before it is returned in the JSON response or an empty response is returned.
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450


## Branches

### List branches

Lists all branches of a project.

```
GET /projects/:id/repository/branches
```

Parameters:

+ `id` (required) - The ID of the project

Marin Jankovski's avatar
Marin Jankovski committed
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499
```json
[
  {
    "name":"async",
    "commit": {
      "id":"a2b702edecdf41f07b42653eb1abe30ce98b9fca",
      "parents": [{
        "id":"3f94fc7c85061973edc9906ae170cc269b07ca55"
      }],
      "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee",
      "message":"give caolan his credit where it's due (up top)",
      "author": {
        "name":"Jeremy Ashkenas",
        "email":"jashkenas@example.com"
      },
      "committer": {
        "name":"Jeremy Ashkenas",
        "email":"jashkenas@example.com"
      },
      "authored_date":"2010-12-08T21:28:50+00:00",
      "committed_date":"2010-12-08T21:28:50+00:00"
    },
    "protected":false
  },
  {
    "name": "gh-pages",
    "commit": {
      "id": "101c10a60019fe870d21868835f65c25d64968fc",
      "parents": [{
        "id": "9c15d2e26945a665131af5d7b6d30a06ba338aaa"
      }],
      "tree": "fb5cc9d45da3014b17a876ad539976a0fb9b352a",
      "message": "Underscore.js 1.5.2",
      "author": {
        "name": "Jeremy Ashkenas",
        "email": "jashkenas@example.com"
      },
      "committer": {
        "name": "Jeremy Ashkenas",
        "email": "jashkenas@example.com"
      },
      "authored_date": "2013-09-07T12: 58: 21+00: 00",
      "committed_date": "2013-09-07T12: 58: 21+00: 00"
    },
    "protected": false
  }
]

```
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541

### List single branch

Lists a specific branch of a project.

```
GET /projects/:id/repository/branches/:branch
```

Parameters:

+ `id` (required) - The ID of the project.
+ `branch` (required) - The name of the branch.


### Protect single branch

Protects a single branch of a project.

```
PUT /projects/:id/repository/branches/:branch/protect
```

Parameters:

+ `id` (required) - The ID of the project.
+ `branch` (required) - The name of the branch.


### Unprotect single branch

Unprotects a single branch of a project.

```
PUT /projects/:id/repository/branches/:branch/unprotect
```

Parameters:

+ `id` (required) - The ID of the project.
+ `branch` (required) - The name of the branch.

542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565

## Admin fork relation

Allows modification of the forked relationship between existing projects. . Available only for admins.

### Create a forked from/to relation between existing projects.

```
POST /projects/:id/fork/:forked_from_id
```

Parameters:

+ `id` (required) - The ID of the project
+ `forked_from_id:` (required) - The ID of the project that was forked from

### Delete an existing forked from relationship

```
DELETE /projects/:id/fork
```

Parameter:

566
+ `id` (required) - The ID of the project
567 568 569 570 571 572 573 574 575 576 577 578 579


## Search for projects by name

Search for projects by name which are public or the calling user has access to

```
GET /projects/search/:query
```

Parameters:

+   query (required) - A string contained in the project name
580 581
+   per_page (optional) - number of projects to return per page
+   page (optional) - the page to retrieve