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  ```