1.. 2 This is a partially generated document. You can modify it in incremental manner using following command: 3 pip install watchdog # install watchmedo 4 make html # to do once 5 watchmedo shell-command -p '*.rst' -c 'time sphinx-build -b html -d _build/doctrees -q . _build/html developer/rest.rst' -wR # will re-run each time you modify rst file 6 7.. _REST_API: 8 9REST API 10======== 11 12The REST API is a public interface which can be used by external code to control Buildbot. 13Internally, the REST API is a thin wrapper around the data API's "Getter" and "Control" sections. 14It is also designed, in keeping with REST principles, to be discoverable. 15As such, the details of the paths and resources are not documented here. 16Begin at the root URL, and see the :ref:`Data_API` documentation for more information. 17 18The precise specifications in RAML format are described in :ref:`REST_API_specs` documentation. 19 20.. contents:: :local: 21 22Versions 23~~~~~~~~ 24 25The API described here is version 2. 26The ad-hoc API from Buildbot-0.8.x, version 1, is no longer supported [#apiv1]_. 27 28 29The policy for incrementing the version is when there is an incompatible change added. 30Removing a field or endpoint is considered incompatible change. 31Adding a field or endpoint is not considered incompatible, and thus will only be described as a change in release notes. 32The policy is that we will avoid as much as possible incrementing the version. 33 34.. [#apiv1] The JSON API defined by ``status_json.py`` in Buildbot-0.8.x is considered version 1, although its root path was ``json``, not ``api/v1``. 35 36Getting 37~~~~~~~ 38 39To get data, issue a GET request to the appropriate path. 40For example, with a base URL of ``http://build.example.org/buildbot``, the list of masters for builder 9 is available at ``http://build.example.org/buildbot/api/v2/builders/9/masters``. 41 42.. bb:rtype:: collection 43 44Collections 45~~~~~~~~~~~ 46 47Results are formatted in keeping with the `JSON API <http://jsonapi.org/>`_ specification. 48The top level of every response is an object. 49Its keys are the plural names of the resource types, and the values are lists of objects, even for a single-resource request. 50For example: 51 52.. code-block:: json 53 54 { 55 "meta": { 56 "total": 2 57 }, 58 "schedulers": [ 59 { 60 "master": null, 61 "name": "smoketest", 62 "schedulerid": 1 63 }, 64 { 65 "master": { 66 "active": true, 67 "last_active": 1369604067, 68 "link": "http://build.example.org/api/v2/master/1", 69 "masterid": 1, 70 "name": "master3:/BB/master" 71 }, 72 "name": "goaheadtryme", 73 "schedulerid": 2 74 } 75 ] 76 } 77 78A response may optionally contain extra, related resources beyond those requested. 79The ``meta`` key contains metadata about the response, including the total count of resources in a collection. 80 81Several query parameters may be used to affect the results of a request. 82These parameters are applied in the order described (so, it is not possible to sort on a field that is not selected, for example). 83 84Field Selection 85............... 86 87If only certain fields of each resource are required, the ``field`` query parameter can be used to select them. 88For example, the following will select just the names and id's of all schedulers: 89 90* ``http://build.example.org/api/v2/scheduler?field=name&field=schedulerid`` 91 92Field selection can be used for either detail (single-entity) or collection (multi-entity) requests. 93The remaining options only apply to collection requests. 94 95Filtering 96......... 97 98Collection responses may be filtered on any simple top-level field. 99 100To select records with a specific value use the query parameter ``{field}={value}``. 101For example, ``http://build.example.org/api/v2/scheduler?name=smoketest`` selects the scheduler named "smoketest". 102 103Filters can use any of the operators listed below, with query parameters of the form ``{field}__{operator}={value}``. 104 105``eq`` 106 equality, with the same parameter appearing one or multiple times, is equality with one of the given values (so `foo__eq=x&foo__eq=y` would match resources where foo is `x` or `y`) 107``ne`` 108 inequality, or set exclusion 109``lt`` 110 select resources where the field's value is less than ``{value}`` 111``le`` 112 select resources where the field's value is less than or equal to ``{value}`` 113``gt`` 114 select resources where the field's value is greater than ``{value}`` 115``ge`` 116 select resources where the field's value is greater than or equal to ``{value}`` 117``contains`` 118 Select resources where the field's value contains ``{value}``. 119 If the parameter is provided multiple times, results containing at least one of the values are returned (so `foo__contains=x&foo__contains=y` would match resources where foo contains `x`, `y` or both). 120 121For example: 122 123* ``http://build.example.org/api/v2/builder?name__lt=cccc`` 124* ``http://build.example.org/api/v2/buildsets?complete__eq=false`` 125 126Boolean values can be given as ``on``/``off``, ``true``/``false``, ``yes``/``no``, or ``1``/``0``. 127 128Sorting 129....... 130 131Collection responses may be ordered with the ``order`` query parameter. 132This parameter takes a field name to sort on, optionally prefixed with ``-`` to reverse the sort. 133The parameter can appear multiple times, and will be sorted lexicographically with the fields arranged in the given order. 134For example: 135 136* ``http://build.example.org/api/v2/buildrequests?order=builderid&order=buildrequestid`` 137 138Pagination 139.......... 140 141Collection responses may be paginated with the ``offset`` and ``limit`` query parameters. 142The offset is the 0-based index of the first result to include, after filtering and sorting. 143The limit is the maximum number of results to return. 144Some resource types may impose a maximum on the limit parameter; be sure to check the resulting links to determine whether further data is available. 145For example: 146 147* ``http://build.example.org/api/v2/buildrequests?order=builderid&limit=10`` 148* ``http://build.example.org/api/v2/buildrequests?order=builderid&offset=20&limit=10`` 149 150Controlling 151~~~~~~~~~~~ 152 153Data API control operations are handled by POST requests using a simplified form of `JSONRPC 2.0 <http://www.jsonrpc.org/specification>`_. 154The JSONRPC "method" is mapped to the data API "action", and the parameters are passed to that application. 155 156The following parts of the protocol are not supported: 157 158* positional parameters 159* batch requests 160 161Requests are sent as an HTTP POST, containing the request JSON in the body. 162The content-type header must be ``application/json``. 163 164A simple example: 165 166.. code-block:: none 167 168 POST http://build.example.org/api/v2/scheduler/4 169 --> {"jsonrpc": "2.0", "method": "force", 170 "params": {"revision": "abcd", "branch": "dev"}, 171 "id": 843} 172 <-- {"jsonrpc": "2.0", "result": {"buildsetid": 44}, "id": 843} 173 174Authentication 175~~~~~~~~~~~~~~ 176 177Authentication to the REST API is performed in the same manner as authentication to the main web interface. 178Once credentials have been established, a cookie will be set, which must be sent to the Buildbot REST API with every request thereafter. 179 180.. code-block:: python 181 182 import requests 183 s = requests.Session() 184 s.get("https://<buildbot_url>/auth/login", auth=('user', 'passwd')) 185 builders = s.get("https://<buildbot_url>/api/v2/builders").json() 186 187For those Buildbot instances using OAuth2 authentication providers, it is at the moment not possible to access the authenticated API . 188