github.com/billybanfield/evergreen@v0.0.0-20170525200750-eeee692790f7/service/REST_README.md (about) 1 Evergreen REST API v1 2 ---------- 3 4 ### Contents 5 6 - [A note on authentication](#a-note-on-authentication) 7 - [Retrieve a list of active projects](#retrieve-a-list-of-active-projects) 8 - [Retrieve info on a particular project](#retrieve-info-on-a-particular-project) 9 - [Retrieve the most recent revisions for a particular project](#retrieve-the-most-recent-revisions-for-a-particular-project) 10 - [Retrieve a version with passing builds](#retrieve-a-version-with-passing-builds) 11 - [Retrieve info on a particular version](#retrieve-info-on-a-particular-version) 12 - [Retrieve info on a particular version by its revision](#retrieve-info-on-a-particular-version-by-its-revision) 13 - [Activate a particular version](#activate-a-particular-version) 14 - [Retrieve the status of a particular version](#retrieve-the-status-of-a-particular-version) 15 - [Retrieve info on a particular build](#retrieve-info-on-a-particular-build) 16 - [Retrieve the status of a particular build](#retrieve-the-status-of-a-particular-build) 17 - [Retrieve info on a particular task](#retrieve-info-on-a-particular-task) 18 - [Retrieve the status of a particular task](#retrieve-the-status-of-a-particular-task) 19 - [Retrieve the most recent revisions for a particular kind of task](#retrieve-the-most-recent-revisions-for-a-particular-kind-of-task) 20 21 #### A note on authentication 22 23 Most of the these REST endpoints do not require authentication to access. 24 However, if the task, build, version, etc. that you are attempting to access is part of a private project, auth information is required to access. 25 Attempts to load private pages with a public REST call receive a 302 FOUND response. 26 27 The simplest way to do this is to use your `user` and `api_key` fields from the Settings page. 28 Authenticated REST access requires setting two headers, `Auth-Username` and `Api-Key`. 29 30 ##### Example 31 32 ```bash 33 curl -H Auth-Username:my.name -H Api-Key:21312mykey12312 https://localhost:9090/rest/v1/projects/my_private_project 34 ``` 35 #### Retrieve a list of active project IDs 36 37 GET /rest/v1/projects 38 39 _Note that you must use API credentials to see private projects._ 40 41 ##### Request 42 43 curl https://localhost:9090/rest/v1/projects 44 45 ##### Response 46 47 ```json 48 { 49 "projects": [ 50 "mci", 51 "mongodb-mongo-master-sanitize", 52 "mongo-c-driver" 53 ] 54 } 55 ``` 56 57 #### Retrieve info on a particular project 58 59 GET /rest/v1/projects/{project_id} 60 61 _Note that you must use API credentials to see private projects._ 62 63 ##### Request 64 65 curl https://localhost:9090/rest/v1/projects/mci 66 67 ##### Response 68 69 ```json 70 { 71 "owner_name": "evergreen-ci", 72 "repo_name": "evergreen", 73 "branch_name": "master", 74 "repo_kind": "github", 75 "enabled": true, 76 "private": false, 77 "batch_time": 1200, 78 "remote_path": "self-tests.yml", 79 "identifier": "mci", 80 "display_name": "Evergreen Self-Tests", 81 "local_config": "", 82 "deactivate_previous": true, 83 "tracked": true, 84 "repotracker_error": null 85 } 86 ``` 87 88 #### Retrieve the most recent revisions for a particular project 89 90 GET /rest/v1/projects/{project_id}/versions 91 92 ##### Request 93 94 curl https://localhost:9090/rest/v1/projects/mongodb-mongo-master/versions 95 96 ##### Response 97 98 ```json 99 { 100 "project": "mongodb-mongo-master", 101 "versions": [ 102 { 103 "version_id": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 104 "author": "Eric Milkie", 105 "revision": "d477da53e119b207de45880434ccef1e47084652", 106 "message": "SERVER-14613 corrections for gcc", 107 "builds": { 108 "amazon": { 109 "build_id": "mongodb_mongo_master_amazon_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 110 "name": "Amazon 64-bit", 111 "tasks": { 112 "aggregation": { 113 "task_id": "mongodb_mongo_master_amazon_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09_aggregation_amazon", 114 "status": "undispatched", 115 "time_taken": 0 116 }, 117 "aggregation_auth": { ... }, 118 ... 119 } 120 }, 121 "debian71": { ... }, 122 } 123 }, 124 { 125 "version_id": "mongodb_mongo_master_d30aac993ecc88052f11946e4486050ff57ba89c", 126 ... 127 }, 128 ... 129 ] 130 } 131 ``` 132 133 #### Retrieve a version with passing builds 134 135 GET /rest/v1/projects/{project_id}/last_green?{variants} 136 137 ##### Parameters 138 139 This endpoint requires a query string listing the variants the user would like to ensure are passing. 140 Each variant is provided as a separate field (field values are not required: `?rhel55&osx-1010` is equivalent to `?rhel55=1&osx-1010=1`). 141 142 At least one variant is required. 143 144 ##### Request 145 146 curl https://localhost:9090/rest/v1/projects/mongodb-mongo-master/last_green?rhel55=1&rhel62=1 147 148 ##### Response 149 150 The project's most recent version for which the variants provided in the query string are completely successful (i.e. "green"). 151 The response contains the [entire version document](#retrieve-info-on-a-particular-version). 152 153 154 155 156 #### Retrieve info on a particular version by its revision 157 158 GET /rest/v1/projects/{project_id}/revisions/{revision} 159 160 or 161 162 GET /rest/v1/projects/{project_id}/revisions/{revision} 163 164 _Note that the revision is equivalent to the git hash._ 165 166 ##### Request 167 168 curl https://localhost:9090/rest/v1/projects/mongodb-mongo-master/revisions/d477da53e119b207de45880434ccef1e47084652 169 170 ##### Response 171 172 ```json 173 { 174 "id": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 175 "create_time": "2014-07-22T13:02:09.162-04:00", 176 "start_time": "2014-07-22T13:03:18.151-04:00", 177 "finish_time": "0001-01-01T00:00:00Z", 178 "project": "mongodb-mongo-master", 179 "revision": "d477da53e119b207de45880434ccef1e47084652", 180 "author": "Eric Milkie", 181 "author_email": "milkie@10gen.com", 182 "message": "SERVER-14613 corrections for gcc", 183 "status": "started", 184 "activated": true, 185 "builds": [ 186 "mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 187 "mongodb_mongo_master_linux_64_debug_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 188 ... 189 ], 190 "build_variants": [ 191 "Linux 64-bit", 192 "Linux 64-bit DEBUG", 193 ... 194 ], 195 "order": 4205, 196 "owner_name": "mongodb", 197 "repo_name": "mongo", 198 "branch_name": "master", 199 "repo_kind": "github", 200 "batch_time": 0, 201 "identifier": "mongodb-mongo-master", 202 "remote": false, 203 "remote_path": "", 204 "requester": "gitter_request" 205 } 206 ``` 207 208 #### Retrieve info on a particular version 209 210 GET /rest/v1/versions/{version_id} 211 212 ##### Request 213 214 curl https://localhost:9090/rest/v1/versions/mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652 215 216 ##### Response 217 218 ```json 219 { 220 "id": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 221 "create_time": "2014-07-22T13:02:09.162-04:00", 222 "start_time": "2014-07-22T13:03:18.151-04:00", 223 "finish_time": "0001-01-01T00:00:00Z", 224 "project": "mongodb-mongo-master", 225 "revision": "d477da53e119b207de45880434ccef1e47084652", 226 "author": "Eric Milkie", 227 "author_email": "milkie@10gen.com", 228 "message": "SERVER-14613 corrections for gcc", 229 "status": "started", 230 "activated": true, 231 "builds": [ 232 "mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 233 "mongodb_mongo_master_linux_64_debug_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 234 ... 235 ], 236 "build_variants": [ 237 "Linux 64-bit", 238 "Linux 64-bit DEBUG", 239 ... 240 ], 241 "order": 4205, 242 "owner_name": "mongodb", 243 "repo_name": "mongo", 244 "branch_name": "master", 245 "repo_kind": "github", 246 "batch_time": 0, 247 "identifier": "mongodb-mongo-master", 248 "remote": false, 249 "remote_path": "", 250 "requester": "gitter_request" 251 } 252 ``` 253 254 #### Retrieve the YAML configuration for a specific version 255 256 GET /rest/v1/versions/{version_id}/config 257 258 ##### Request 259 260 curl https://localhost:9090/rest/v1/versions/mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652/config 261 262 ##### Response 263 264 The contents of the YAML config for the specified version will be sent back in the body of the request, using 265 the header `Content-Type: application/x-yaml`. 266 267 268 #### Activate a particular version 269 270 PATCH /rest/v1/versions/{version_id} 271 272 ##### Input 273 274 Name | Type | Description 275 --------- | ---- | ----------- 276 activated | bool | **Optional**. Activates the version when `true`, and deactivates the version when `false`. Does nothing if the field is omitted. 277 278 ##### Request 279 280 curl -X PATCH https://localhost:9090/rest/v1/versions/mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652 -d '{"activated": false}' -H Auth-Username:my.name -H Api-Key:21312mykey12312 281 282 ##### Response 283 284 ```json 285 { 286 "id": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 287 "create_time": "2014-07-22T13:02:09.162-04:00", 288 "start_time": "2014-07-22T13:03:18.151-04:00", 289 "finish_time": "0001-01-01T00:00:00Z", 290 "project": "mongodb-mongo-master", 291 "revision": "d477da53e119b207de45880434ccef1e47084652", 292 "author": "Eric Milkie", 293 "author_email": "milkie@10gen.com", 294 "message": "SERVER-14613 corrections for gcc", 295 "status": "started", 296 "activated": false, 297 "builds": [ 298 "mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 299 "mongodb_mongo_master_linux_64_debug_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 300 ... 301 ], 302 "build_variants": [ 303 "Linux 64-bit", 304 "Linux 64-bit DEBUG", 305 ... 306 ], 307 "order": 4205, 308 "owner_name": "mongodb", 309 "repo_name": "mongo", 310 "branch_name": "master", 311 "repo_kind": "github", 312 "batch_time": 0, 313 "identifier": "mongodb-mongo-master", 314 "remote": false, 315 "remote_path": "", 316 "requester": "gitter_request" 317 } 318 ``` 319 320 #### Retrieve the status of a particular version 321 322 GET /rest/v1/versions/{version_id}/status 323 324 ##### Parameters 325 326 Name | Type | Default | Description 327 ------- | ------ | ------- | ----------- 328 groupby | string | tasks | Determines how to key into the task status. For `tasks` use `task_name.build_variant`, and for `builds` use `build_variant.task_name`. 329 330 331 ##### Request 332 333 curl https://localhost:9090/rest/v1/versions/mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652/status 334 335 ##### Response 336 337 ```json 338 { 339 "version_id": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 340 "tasks": { 341 "aggregation": { 342 "amazon": { 343 "task_id": "mongodb_mongo_master_amazon_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09_aggregation_amazon", 344 "status": "undispatched", 345 "time_taken": 0 346 }, 347 "debian71": { ... }, 348 ... 349 }, 350 "aggregation_auth": { ... }, 351 ... 352 } 353 } 354 ``` 355 356 ##### Request 357 358 curl https://localhost:9090/rest/v1/versions/mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652/status?groupby=builds 359 360 ##### Response 361 362 ```json 363 { 364 "version_id": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 365 "builds": { 366 "amazon": { 367 "aggregation": { 368 "task_id": "mongodb_mongo_master_amazon_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09_aggregation_amazon", 369 "status": "undispatched", 370 "time_taken": 0 371 }, 372 "aggregation_auth": { ... }, 373 ... 374 }, 375 "debian71": { ... }, 376 ... 377 } 378 } 379 ``` 380 381 #### Retrieve info on a particular build 382 383 GET /rest/v1/builds/{build_id} 384 385 ##### Request 386 387 curl https://localhost:9090/rest/v1/builds/mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09 388 389 ##### Response 390 391 ```json 392 { 393 "id": "mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 394 "create_time": "2014-07-22T13:02:09.162-04:00", 395 "start_time": "2014-07-22T13:03:18.151-04:00", 396 "finish_time": "0001-01-01T00:00:00Z", 397 "push_time": "2014-07-22T13:02:09.162-04:00", 398 "version": "mongodb_mongo_master_d477da53e119b207de45880434ccef1e47084652", 399 "project": "mongodb-mongo-master", 400 "revision": "d477da53e119b207de45880434ccef1e47084652", 401 "variant": "linux-64", 402 "number": "7960", 403 "status": "started", 404 "activated": true, 405 "activated_time": "2014-07-22T13:03:07.556-04:00", 406 "order": 4205, 407 "tasks": { 408 "aggregation": { 409 "task_id": "mongodb_mongo_master_amazon_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09_aggregation_amazon", 410 "status": "undispatched", 411 "time_taken": 0 412 }, 413 "aggregation_auth": { ... }, 414 ... 415 }, 416 "time_taken": 0, 417 "name": "Linux 64-bit", 418 "requested": "gitter_request" 419 } 420 ``` 421 422 #### Retrieve the status of a particular build 423 424 GET /rest/v1/builds/{build_id}/status 425 426 ##### Request 427 428 curl https://localhost:9090/rest/v1/builds/mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09/status 429 430 ##### Response 431 432 ```json 433 { 434 "build_id": "mongodb_mongo_master_linux_64_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09", 435 "build_variant": "linux-64", 436 "tasks": { 437 "aggregation": { 438 "task_id": "mongodb_mongo_master_amazon_d477da53e119b207de45880434ccef1e47084652_14_07_22_17_02_09_aggregation_amazon", 439 "status": "undispatched", 440 "time_taken": 0 441 }, 442 "aggregation_auth": { ... }, 443 ... 444 } 445 } 446 ``` 447 448 #### Retrieve info on a particular task 449 450 GET /rest/v1/tasks/{task_id} 451 452 ##### Request 453 454 curl https://localhost:9090/rest/v1/tasks/mongodb_mongo_master_linux_64_7ffac7f351b80f84589349e44693a94d5cc5e14c_14_07_22_13_27_06_aggregation_linux_64 455 456 ##### Response 457 458 ```json 459 { 460 "id": "mongodb_mongo_master_linux_64_7ffac7f351b80f84589349e44693a94d5cc5e14c_14_07_22_13_27_06_aggregation_linux_64", 461 "create_time": "2014-07-22T09:27:06.913-04:00", 462 "scheduled_time": "2014-07-22T10:40:09.485-04:00", 463 "dispatch_time": "2014-07-22T10:44:12.095-04:00", 464 "start_time": "2014-07-22T10:44:15.783-04:00", 465 "finish_time": "2014-07-22T10:49:02.796-04:00", 466 "push_time": "2014-07-22T09:27:06.913-04:00", 467 "version": "mongodb_mongo_master_7ffac7f351b80f84589349e44693a94d5cc5e14c", 468 "project": "mongodb-mongo-master", 469 "revision": "7ffac7f351b80f84589349e44693a94d5cc5e14c", 470 "priority": 0, 471 "last_heartbeat": "2014-07-22T10:48:43.761-04:00", 472 "activated": true, 473 "build_id": "mongodb_mongo_master_linux_64_7ffac7f351b80f84589349e44693a94d5cc5e14c_14_07_22_13_27_06", 474 "distro": "rhel55-test", 475 "build_variant": "linux-64", 476 "depends_on": [ 477 "mongodb_mongo_master_linux_64_7ffac7f351b80f84589349e44693a94d5cc5e14c_14_07_22_13_27_06_compile_linux_64" 478 ], 479 "display_name": "aggregation", 480 "host_id": "i-58e6e573", 481 "restarts": 0, 482 "execution": 0, 483 "archived": false, 484 "order": 4196, 485 "requester": "gitter_request", 486 "status": "success", 487 "status_details": { 488 "timed_out": false, 489 "timeout_stage": "" 490 }, 491 "aborted": false, 492 "time_taken": 287013061125, 493 "expected_duration": 0, 494 "test_results": { 495 "jstests/aggregation/mongos_slaveok.js": { 496 "status": "pass", 497 "time_taken": 25482633113, 498 "logs": { 499 "url": "http://buildlogs.mongodb.org/build/53ce78d7d2a60f5fac000970/test/53ce78d9d2a60f5f72000a23/" 500 } 501 }, 502 "jstests/aggregation/testSlave.js": { ... }, 503 ... 504 }, 505 "min_queue_pos": 0, 506 "files": [] 507 } 508 ``` 509 510 #### Retrieve the status of a particular task 511 512 GET /rest/v1/tasks/{task_id}/status 513 514 ##### Request 515 516 curl https://localhost:9090/rest/v1/tasks/mongodb_mongo_master_linux_64_7ffac7f351b80f84589349e44693a94d5cc5e14c_14_07_22_13_27_06_aggregation_linux_64/status 517 518 ##### Response 519 520 ```json 521 { 522 "task_id": "mongodb_mongo_master_linux_64_7ffac7f351b80f84589349e44693a94d5cc5e14c_14_07_22_13_27_06_aggregation_linux_64", 523 "task_name": "aggregation", 524 "status": "success", 525 "status_details": { 526 "timed_out": false, 527 "timeout_stage": "" 528 }, 529 "tests": { 530 "jstests/aggregation/mongos_slaveok.js": { 531 "status": "pass", 532 "time_taken": 25482633113, 533 "logs": { 534 "url": "http://buildlogs.mongodb.org/build/53ce78d7d2a60f5fac000970/test/53ce78d9d2a60f5f72000a23/" 535 } 536 }, 537 "jstests/aggregation/testSlave.js": { ... }, 538 ... 539 } 540 } 541 ``` 542 543 #### Retrieve the most recent revisions for a particular kind of task 544 545 GET /rest/v1/tasks/{task_name}/history 546 547 ##### Parameters 548 549 Name | Type | Description 550 ------- | ------ | ----------- 551 project | string | The project name. 552 553 554 ##### Request 555 556 curl https://localhost:9090/rest/v1/tasks/compile/history?project=sample 557 558 ##### Response 559 560 ```json 561 { 562 "Tasks": [ 563 { 564 "_id": "3585388b1591dfca47ac26a5b9a564ec8f138a5e", 565 "order": 4, 566 "tasks": [ 567 { 568 "_id": "sample_osx_108_3585388b1591dfca47ac26a5b9a564ec8f138a5e_14_08_12_21_23_53_compile_osx_108", 569 "activated": true, 570 "build_variant": "osx-108", 571 "status": "undispatched", 572 "status_details": {}, 573 "time_taken": 0 574 }, 575 { 576 "_id": "sample_ubuntu_3585388b1591dfca47ac26a5b9a564ec8f138a5e_14_08_12_21_23_53_compile_ubuntu", 577 ... 578 }, 579 ... 580 ] 581 }, 582 { 583 "_id": "9b20d123699a8061ac9587784a6871cf58d4e78f", 584 ... 585 } 586 ], 587 "Versions": [ 588 { 589 "id": "sample_3585388b1591dfca47ac26a5b9a564ec8f138a5e", 590 "create_time": "2014-08-12T21:23:53.555-04:00", 591 "start_time": "0001-01-01T00:00:00Z", 592 "finish_time": "0001-01-01T00:00:00Z", 593 "revision": "3585388b1591dfca47ac26a5b9a564ec8f138a5e", 594 "message": "dont print for timeouts", 595 "order": 4 596 }, 597 { 598 "id": "sample_9b20d123699a8061ac9587784a6871cf58d4e78f", 599 ... 600 }, 601 ... 602 ], 603 "FailedTests": {}, 604 "Exhausted": { 605 "Before": true, 606 "After": true 607 } 608 } 609 ```