github.com/billybanfield/evergreen@v0.0.0-20170525200750-eeee692790f7/apiv3/how_to.rst (about)

     1  ======================
     2  REST V2 Use Case Guide
     3  ======================
     4  
     5   This guide presents users with information on how to perform some commonly 
     6  desired actions in the Evergreen API.
     7  
     8  Find all failures of a given build
     9  ----------------------------------
    10  
    11  Endpoint
    12  ~~~~~~~~~
    13  
    14  ``GET /builds/<build_id>/tasks`` 
    15  
    16  Description
    17  ~~~~~~~~~~~
    18  
    19  To better understand the state of a build, perhaps when attempting to determine 
    20  the quality of a build for a release, it is helpful to be able to fetch information 
    21  about the tasks it ran. To fetch this data, make a call to the ``GET /builds/<build_id>/tasks`` 
    22  endpoint. Page through the results task data to produce meaningful statistics 
    23  like the number of task failures or percentage of failures of a given build.
    24  
    25  Find detailed information about the status of a particular tasks and its tests
    26  ------------------------------------------------------------------------------
    27  
    28  Endpoints
    29  ~~~~~~~~~
    30  
    31  ``GET /tasks/<task_id>`` 
    32  
    33  ``GET /tasks/<task_id>/tests``
    34  
    35  Description
    36  ~~~~~~~~~~~
    37  
    38  To better understand all aspects of a task failure, such as failure mode, 
    39  which tests failed, and how long it took, it is helpful to fetch this information
    40  about a task. This can be accomplished using 2 API calls. Make one call  
    41  to the endpoint for a specific task ``GET /tasks/<task_id>`` which returns
    42  information about the task itself. Then, make a second cal to ``GET /tasks/<task_id>/tests``
    43  which delivers specific information about the tests that ran in a certain task.
    44  
    45  Get all hosts
    46  -------------
    47  
    48  Endpoint
    49  ~~~~~~~~~
    50  
    51  ``GET /hosts``
    52  
    53  Description
    54  ~~~~~~~~~~~
    55  
    56  Retrieving information on Evergreen's hosts can be helpful for system 
    57  monitoring. To fetch this information, make a call to ``GET /hosts``, which 
    58  returns a paginated list of hosts. Page through the results to inspect all hosts.
    59  
    60  Restart all failures for a commit
    61  ---------------------------------
    62  
    63  Endpoints
    64  ~~~~~~~~~
    65  
    66  ``GET /project/<project_name>/versions/<commit_hash>/tasks`` 
    67  
    68  ``POST /tasks/<task_id>/restart`` 
    69  
    70  Description
    71  ~~~~~~~~~~~
    72  
    73  Some Evergreen projects contain flaky tests or can endure spurious failures.
    74  To restart all of these tasks to gain better signal a user can fetch all of 
    75  the tasks for a commit. Make a request to to ``GET /project/<project_name>/versions/<commit_hash>/tasks`` 
    76  to fetch the tasks that ran and then loop over all of the returned tasks, 
    77  calling ``POST /tasks/<task_id>/restart`` on each task which has failed.