github.com/billybanfield/evergreen@v0.0.0-20170525200750-eeee692790f7/apiv3/usage.rst (about) 1 ===== 2 Usage 3 ===== 4 5 General Functionality 6 ===================== 7 8 9 Content Type and Communication 10 ------------------------------ 11 The API accepts and returns all results in JSON. Some resources also allow 12 URL parameters to provide additional specificity to a request. 13 14 Errors 15 ------ 16 When an error is encountered during a request, the API returns a JSON 17 object with the HTTP status code and a message describing the error of the form: 18 19 :: 20 21 { 22 "status": <http_status_code>, 23 "error": <error message> 24 } 25 26 Pagination 27 ---------- 28 API Routes that fetch many objects return them in a JSON array and support paging 29 through subsets of the total result set. When there are additional results for the 30 query, access to them is populated in a 'Links' HTTP header. This header has the form: 31 32 :: 33 34 "Links" : <http://<EVERGREEN_HOST>/rest/v2/path/to/resource?start_at=<pagination_key>&limit=<objects_per_page>; rel="next" 35 <http://<EVERGREEN_HOST>/rest/v2/path/to/resource?start_at=<pagination_key>&limit=<objects_per_page>; rel="prev" 36 37 Dates 38 ----- 39 40 Date fields are returned and accepted in ISO-8601 UTC extended format. They contain 41 3 fractional seconds with a ‘dot’ separator. 42 43 Empty Fields 44 ------------ 45 46 A returned object will always contain its complete list of fields. Any field 47 that does not have an associated value will be filled with JSON's null value. 48 49 Resources 50 ========= 51 52 The API has a series of implemented objects that it returns depending on the 53 queried endpoint. 54 55 Task 56 ---- 57 58 ``Base URL``: http://evergreen.mongodb.com/rest/v2/ 59 60 The task is a basic unit of work understood by evergreen. They usually comprise 61 a suite of tests or generation of a set of artifacts. 62 63 Objects 64 ~~~~~~~ 65 66 .. list-table:: **Task** 67 :widths: 25 10 55 68 :header-rows: 1 69 70 * - Name 71 - Type 72 - Description 73 * - ``task_id`` 74 - string 75 - Unique identifier of this task 76 * - ``create_time`` 77 - time 78 - Time that this task was first created 79 * - ``dispatch_time`` 80 - time 81 - Time that this time was dispatched 82 * - ``push_time`` 83 - time 84 - Time that the git commit associated with this task was pushed to github 85 * - ``scheduled_time`` 86 - time 87 - Time that this task is scheduled to begin 88 * - ``start_time`` 89 - time 90 - Time that this task began execution 91 * - ``finish_time`` 92 - time 93 - Time that this task finished execution 94 * - ``version_id`` 95 - string 96 - An identifier of this task by its project and commit hash 97 * - ``branch`` 98 - string 99 - The version control branch that this task is associated with 100 * - ``revision`` 101 - string 102 - The version control identifier associated with this task 103 * - ``priority`` 104 - int 105 - The priority of this task to be run 106 * - ``activated`` 107 - boolean 108 - Whether the task is currently active 109 * - ``activated_by`` 110 - string 111 - Identifier of the process or user that activated this task 112 * - ``build_id`` 113 - string 114 - Identifier of the build that this task is part of 115 * - ``distro_id`` 116 - string 117 - Identifier of the distro that this task runs on 118 * - ``build_variant`` 119 - string 120 - Name of the buildvariant that this task runs on 121 * - ``depends_on`` 122 - array 123 - List of task_ids of task that this task depends on before beginning 124 * - ``display_name`` 125 - string 126 - Name of this task displayed in the UI 127 * - ``host_id`` 128 - string 129 - The ID of the host this task ran or is running on 130 * - ``restarts`` 131 - int 132 - Number of times this task has been restarted 133 * - ``execution`` 134 - int 135 - The number of the execution of this particular task 136 * - ``order`` 137 - int 138 - The position in the commit history of commit this task is associated with 139 * - ``status`` 140 - string 141 - The current status of this task 142 * - ``status_details`` 143 - status_object 144 - Object containing additional information about the status 145 * - logs 146 - logs_object 147 - Object containing additional information about the logs for this task 148 * - time_taken_ms 149 - int 150 - Number of milliseconds this task took during execution 151 * - expected_duration_ms 152 - int 153 - Number of milliseconds expected for this task to execute 154 155 156 .. list-table:: **Logs** 157 :widths: 25 10 55 158 :header-rows: 1 159 160 * - Name 161 - Type 162 - Description 163 * - agent_log 164 - string 165 - Link to logs created by the agent process 166 * - task_log 167 - string 168 - Link to logs created by the task execution 169 * - system_log 170 - string 171 - Link to logs created by the machine running the task 172 * - all_log 173 - string 174 - Link to logs containing merged copy of all other logs 175 176 .. list-table:: **Status** 177 :widths: 25 10 55 178 :header-rows: 1 179 180 * - Name 181 - Type 182 - Description 183 * - status 184 - string 185 - The status of the completed task 186 * - type 187 - string 188 - The method by which the task failed 189 * - desc 190 - string 191 - Description of the final status of this task 192 * - timed_out 193 - boolean 194 - Whether this task ended in a timeout 195 196 Endpoints 197 ~~~~~~~~~ 198 199 List Tasks By Build 200 ``````````````````` 201 202 :: 203 204 GET /builds/<build_id>/tasks 205 206 List all tasks within a specific build 207 208 209 .. list-table:: **Parameters** 210 :widths: 25 10 55 211 :header-rows: 1 212 213 * - Name 214 - Type 215 - Description 216 * - start_at 217 - string 218 - Optional. The identifier of the task to start at in the pagination 219 * - limit 220 - int 221 - Optional. The number of tasks to be returned per page of pagination. Defaults to 100 222 223 List Tasks By Project And Commit 224 ```````````````````````````````` 225 226 :: 227 228 GET /project/<project_name>/versions/<commit_hash>/tasks 229 230 List all tasks within a commit of a given project 231 232 .. list-table:: **Parameters** 233 :widths: 25 10 55 234 :header-rows: 1 235 236 * - Name 237 - Type 238 - Description 239 * - start_at 240 - string 241 - Optional. The identifier of the task to start at in the pagination 242 * - limit 243 - int 244 - Optional. The number of tasks to be returned per page of pagination. Defaults to 100 245 246 247 Get A Single Task 248 ````````````````` 249 250 :: 251 252 GET /tasks/<task_id> 253 254 Fetch a single task using its ID 255 256 Restart A Task 257 `````````````` 258 259 :: 260 261 POST /tasks/<task_id>/restart 262 263 Restarts the task of the given ID. Can only be performed if the task is in progress. 264 265 Change A Task's Execution Status 266 ```````````````````````````````` 267 268 :: 269 270 PATCH /tasks/<task_id> 271 272 Change the current execution status of a task. Accepts a JSON body with the new 273 task status to be set. 274 275 .. list-table:: **Accepted Parameters** 276 :widths: 25 10 55 277 :header-rows: 1 278 279 * - Name 280 - Type 281 - Description 282 * - activated 283 - boolean 284 - The activation status of the task to be set to 285 * - priority 286 - int 287 - The priority of this task's execution. Limited to 100 for non-superusers 288 289 290 For example, to set activate the task and set its status priority to 100, add 291 the following JSON to the request body: 292 293 294 :: 295 296 { 297 "activated": true, 298 "priority": 100 299 } 300 301 302 Test 303 ---- 304 305 ``Base URL``: http://evergreen.mongodb.com/rest/v2/ 306 307 A test is a sub-operation of a task performed by Evergreen. 308 309 Objects 310 ~~~~~~~ 311 312 .. list-table:: **Test** 313 :widths: 25 10 55 314 :header-rows: 1 315 316 * - Name 317 - Type 318 - Description 319 * - task_id 320 - string 321 - Identifier of the task this test is a part of 322 * - Status 323 - string 324 - Execution status of the test 325 * - test_file 326 - string 327 - Name of the test file that this test was run in 328 * - logs 329 - test_log 330 - Object containing information about the logs for this test 331 * - exit_code 332 - int 333 - The exit code of the process that ran this test 334 * - start_time 335 - time 336 - Time that this test began execution 337 * - end_time 338 - time 339 - Time that this test stopped execution 340 341 .. list-table:: **Test Logs** 342 :widths: 25 10 55 343 :header-rows: 1 344 345 * - Name 346 - Type 347 - Description 348 * - url 349 - string 350 - URL where the log can be fetched 351 * - line_num 352 - int 353 - Line number in the log file corresponding to information about this test 354 * - url_raw 355 - string 356 - URL of the unprocessed version of the logs file for this test 357 * - log_id 358 - string 359 - Identifier of the logs corresponding to this test 360 361 Endpoints 362 ~~~~~~~~~ 363 364 Get Tests From A Task 365 ````````````````````` 366 367 :: 368 369 GET /tasks/<task_id>/tests 370 371 Fetches a paginated list of tests that ran as part of the given task 372 373 .. list-table:: **Parameters** 374 :widths: 25 10 55 375 :header-rows: 1 376 377 * - Name 378 - Type 379 - Description 380 * - start_at 381 - string 382 - Optional. The identifier of the test to start at in the pagination 383 * - limit 384 - int 385 - Optional. The number of tets to be returned per page of pagination. Defaults to 100 386 * - status 387 - string 388 - Optional. A status of test to limit the results to. 389 390 Host 391 ---- 392 393 ``Base URL``: http://evergreen.mongodb.com/rest/v2/ 394 395 The hosts resource defines the a running machine instance in Evergreen. 396 397 Objects 398 ~~~~~~~ 399 400 .. list-table:: **Host** 401 :widths: 25 10 55 402 :header-rows: 1 403 404 * - Name 405 - Type 406 - Description 407 * - host_id 408 - string 409 - Unique identifier of a specific host 410 * - distro 411 - distro_info 412 - Object containing information about the distro type of this host 413 * - started_by 414 - string 415 - Name of the process or user that started this host 416 * - host_type 417 - string 418 - The instance type requested for the provider, primarily used for ec2 dynamic hosts 419 * - user 420 - string 421 - The user associated with this host. Set if this host was spawned for a specific user 422 * - status 423 - string 424 - The current state of the host 425 * - running_task 426 - task_info 427 - Object containing information about the task the host is currently running 428 429 .. list-table:: **Distro Info** 430 :widths: 25 10 55 431 :header-rows: 1 432 433 * - Name 434 - Type 435 - Description 436 * - distro_id 437 - string 438 - Unique Identifier of this distro. Can be used to fetch more informaiton about this distro 439 * - provider 440 - string 441 - The service which provides this type of machine 442 443 .. list-table:: **Task Info** 444 :widths: 25 10 55 445 :header-rows: 1 446 447 * - Name 448 - Type 449 - Description 450 * - task_id 451 - string 452 - Unique Identifier of this task. Can be used to fetch more informaiton about this task 453 * - name 454 - string 455 - The name of this task 456 * - dispatch_time 457 - time 458 - Time that this task was dispatched to this host 459 * - version_id 460 - string 461 - Unique identifier for the version of the project that this task is run as part of 462 * - build_id 463 - string 464 - Unique identifier for the build of the project that this task is run as part of 465 466 467 Endpoints 468 ~~~~~~~~~ 469 470 Fetch All Hosts 471 ``````````````` 472 473 :: 474 475 GET /hosts 476 477 Returns a paginated list of all hosts in Evergreen 478 479 .. list-table:: **Parameters** 480 :widths: 25 10 55 481 :header-rows: 1 482 483 * - Name 484 - Type 485 - Description 486 * - start_at 487 - string 488 - Optional. The identifier of the host to start at in the pagination 489 * - limit 490 - int 491 - Optional. The number of hosts to be returned per page of pagination. Defaults to 100 492 * - status 493 - string 494 - Optional. A status of host to limit the results to