3.2.1. REST API

The REST API is a thin wrapper around the data API's "Getter" and "Control" sections. It is also designed, in keeping with REST principles, to be discoverable. As such, the details of the paths and resources are not documented here. Begin at the root URL, and see the Data API documentation for more information.

3.2.1.1. Versions

The API described here is version 2. The ad-hoc API from Buildbot-0.8.x, version 1, is no longer supported.

The policy for incrementing the version is when there is incompatible change added. Removing a field or endpoint is considered incompatible change. Adding a field or endpoint is not considered incompatible, and thus will only be described as a change in release note. The policy is that we will avoid as much as possible incrementing version.

3.2.1.2. Getting

To get data, issue a GET request to the appropriate path. For 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/builder/9/master.

resource type: collection

3.2.1.3. Collections

Results are formatted in keeping with the JSON API specification. The top level of every response is an object. Its keys are the plural names of the resource types, and the values are lists of objects, even for a single-resource request. For example:

{
  "meta": {
    "total": 2
  },
  "schedulers": [
    {
      "master": null,
      "name": "smoketest",
      "schedulerid": 1
    },
    {
      "master": {
        "active": true,
        "last_active": 1369604067,
        "link": "http://build.example.org/api/v2/master/1",
        "masterid": 1,
        "name": "master3:/BB/master"
      },
      "name": "goaheadtryme",
      "schedulerid": 2
    }
  ]
}

A response may optionally contain extra, related resources beyond those requested. The meta key contains metadata about the response, including the total count of resources in a collection.

Several query parameters may be used to affect the results of a request. These parameters are applied in the order described (so, it is not possible to sort on a field that is not selected, for example).

Field Selection

If only certain fields of each resource are required, the field query parameter can be used to select them. For example, the following will select just the names and id's of all schedulers:

  • http://build.example.org/api/v2/scheduler?field=name&field=schedulerid

Field selection can be used for either detail (single-entity) or collection (multi-entity) requests. The remaining options only apply to collection requests.

Filtering

Collection responses may be filtered on any simple top-level field.

To select records with a specific value use the query parameter {field}={value}. For example, http://build.example.org/api/v2/scheduler?name=smoketest selects the scheduler named "smoketest".

Filters can use any of the operators listed below, with query parameters of the form {field}__{operator}={value}.

eq
equality, or with the same parameter appearing multiple times, equality with one of the given values (so foo__eq=x&foo__eq=y would match resources where foo is x or y)
ne
inequality, or set exclusion
lt
select resources where the field's value is less than {value}
le
select resources where the field's value is less than or equal to {value}
gt
select resources where the field's value is greater than {value}
ge
select resources where the field's value is greater than or equal to {value}
contains
select resources where the field's value contains {value}

For example:

  • http://build.example.org/api/v2/builder?name__lt=cccc
  • http://build.example.org/api/v2/buildsets?complete__eq=false

Boolean values can be given as on/off, true/false, yes/no, or 1/0.

Sorting

Collection responses may be ordered with the order query parameter. This parameter takes a field name to sort on, optionally prefixed with - to reverse the sort. The parameter can appear multiple times, and will be sorted lexically with the fields arranged in the given order. For example:

  • http://build.example.org/api/v2/buildrequest?order=builderid&order=buildrequestid

3.2.1.4. Controlling

Data API control operations are handled by POST requests using a simplified form of JSONRPC 2.0. The JSONRPC "method" is mapped to the data API "action", and the parameters are passed to that application.

The following parts of the protocol are not supported:

  • positional parameters
  • batch requests

Requests are sent as an HTTP POST, containing the request JSON in the body. The content-type header must be application/json.

A simple example:

POST http://build.example.org/api/v2/scheduler/4
--> {"jsonrpc": "2.0", "method": "force", "params": {"revision": "abcd", "branch": "dev"}, "id": 843}
<-- {"jsonrpc": "2.0", "result": {"buildsetid": 44}, "id": 843}

3.2.1.5. Raml Specs

The Data API is documented in RAML 1.0 format. RAML describes and documents all our data, rest, and javascript APIs in a format that can be easily manipulated by human and machines.

Build

resource type: build
Attributes:
  • buildid (integer) -- the unique ID of this build
  • number (integer) -- the number of this build (sequential for a given builder)
  • builderid (integer) -- id of the builder for this build
  • buildrequestid (integer) -- build request for which this build was performed, or None if no such request exists
  • workerid (integer) -- the worker this build ran on
  • masterid (integer) -- the master this build ran on
  • started_at (date) -- time at which this build started
  • complete (boolean) -- true if this build is complete Note that this is a calculated field (from complete_at != None). Ordering by this field is not optimized by the database layer.
  • complete_at? (date) -- time at which this build was complete, or None if it's still running
  • properties? (sourcedproperties) -- a dictionary of properties attached to build.
  • results? (integer) -- the results of the build (see Build Result Codes), or None if not complete
  • state_string (string) -- a string giving detail on the state of the build.

example

{
    "builderid": 10,
    "buildid": 100,
    "buildrequestid": 13,
    "workerid": 20,
    "complete": false,
    "complete_at": null,
    "masterid": 824,
    "number": 1,
    "results": null,
    "started_at": 1451001600,
    "state_string": "created",
    "properties": {}
}

This resource type describes completed and in-progress builds. Much of the contextual data for a build is associated with the build request, and through it the buildset.

Note

properties

This properties dict is only filled out if the properties filterspec is set.

Meaning that, property filter allows one to request the Builds DATA API like so:

  • api/v2/builds?property=propKey1&property=propKey2 (returns Build's properties which match given keys)
  • api/v2/builds?property=* (returns all Build's properties)
  • api/v2/builds?propKey1&property=propKey2&limit=30 (filters combination)

Important

When combined with field filter, to get properties, one should ensure properties field is set.

  • api/v2/builds?field=buildid&field=properties&property=workername&property=user

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.builds.Build
newBuild(builderid, buildrequestid, workerid)
Parameters:
  • builderid (integer) -- builder performing this build
  • buildrequstid (integer) -- build request being built
  • workerid (integer) -- worker on which this build is performed
Returns:

(buildid, number) via Deferred

Create a new build resource and return its ID. The state strings for the new build will be set to 'starting'.

setBuildStateString(buildid, state_string)
Parameters:
  • buildid (integer) -- the build to modify
  • state_string (unicode) -- new state string for this build

Replace the existing state strings for a build with a new list.

finishBuild(buildid, results)
Parameters:
  • buildid (integer) -- the build to modify
  • results (integer) -- the build's results

Mark the build as finished at the current time, with the given results.

Endpoints

path: /builders/{builderid}/builds
Path Keys:builderid (number) -- the ID of the builder

This path selects all builds for a builder (can return lots of data!)

GET
returns
collection of build
path: /builders/{builderid}/builds/{build_number}
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder

This path selects a specific build by builderid, buildnumber

GET
returns
collection of build
POST with method: /builders/{builderid}/builds/{build_number}:stop
Body keys:
  • method (string) -- must be stop
  • reason (string) -- The reason why the build was stopped
  • results (integer) -- optionally results value override (default CANCELLED)
POST with method: /builders/{builderid}/builds/{build_number}:rebuild
Body keys:method (string) -- must be rebuild
path: /buildrequests/{buildrequestid}/builds
Path Keys:buildrequestid (number) -- the id of the buildrequest
GET
returns
collection of build
path: /builds
GET
returns
collection of build
path: /builds/{buildid}
Path Keys:buildid (number) -- the id of the build

This path selects a build by id

GET
returns
collection of build
POST with method: /builds/{buildid}:stop
Body keys:
  • method (string) -- must be stop
  • reason (string) -- The reason why the build was stopped
POST with method: /builds/{buildid}:rebuild
Body keys:method (string) -- must be rebuild

builder

resource type: builder
Attributes:
  • builderid (integer) -- the ID of this builder
  • description? (string) -- The description for that builder
  • masterids[] (integer) -- the ID of the masters this builder is running on
  • name (identifier) -- builder name
  • tags[] (string) -- list of tags for this builder

This resource type describes a builder.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.builders.Builder
updateBuilderList(masterid, builderNames)
Parameters:
  • masterid (integer) -- this master's master ID
  • builderNames (list) -- list of names of currently-configured builders (unicode strings)
Returns:

Deferred

Record the given builders as the currently-configured set of builders on this master. Masters should call this every time the list of configured builders changes.

Endpoints

path: /builders

This path selects all builders

GET
returns
collection of builder
path: /builders/{builderid}
Path Keys:builderid (number) -- the ID of the builder

This path selects a builder by builderid

GET
returns
collection of builder
path: /masters/{masterid}/builders
Path Keys:masterid (number) -- the id of the master

This path selects all builders of a given master

GET
returns
collection of builder
path: /masters/{masterid}/builders/{builderid}
Path Keys:
  • masterid (number) -- the id of the master
  • builderid (number) -- the id of the builder

This path selects one builder by id of a given master

GET
returns
collection of builder

buildrequest

resource type: buildrequest
Attributes:
  • buildrequestid (integer) -- the unique ID of this buildrequest
  • builderid (integer) -- the id of the builder linked to this buildrequest
  • buildsetid (integer) -- the id of the buildset that contains this buildrequest
  • claimed (boolean) -- True if this buildrequest has been claimed. Note that this is a calculated field (from claimed_at != None). Ordering by this field is not optimized by the database layer.
  • claimed_at? (date) -- time at which this build has last been claimed. None if this buildrequest has never been claimed or has been unclaimed
  • claimed_by_masterid? (integer) -- the id of the master that claimed this buildrequest. None if this buildrequest has never been claimed or has been unclaimed
  • complete (boolean) -- true if this buildrequest is complete
  • complete_at? (date) -- time at which this buildrequest was completed, or None if it's still running
  • priority (integer) -- the priority of this buildrequest
  • results? (integer) -- the results of this buildrequest (see Build Result Codes), or None if not complete
  • submitted_at (date) -- time at which this buildrequest were submitted
  • waited_for (boolean) -- True if the entity that triggered this buildrequest is waiting for it to complete. Should be used by an (unimplemented so far) clean shutdown to only start br that are waited_for.

This resource type describes completed and in-progress buildrequests. Much of the contextual data for a buildrequest is associated with the buildset that contains this buildrequest.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.buildrequests.BuildRequest
claimBuildRequests(brids, claimed_at=None, _reactor=twisted.internet.reactor)
Parameters:
  • brids (list(integer)) -- list of buildrequest id to claim
  • claimed_at (datetime) -- date and time when the buildrequest is claimed
  • _reactor (twisted.internet.interfaces.IReactorTime) -- reactor used to get current time if claimed_at is None
Returns:

(boolean) whether claim succeeded or not

Claim a list of buildrequests

reclaimBuildRequests(brids, _reactor=twisted.internet.reactor)
Parameters:
  • brids (list(integer)) -- list of buildrequest id to reclaim
  • _reactor (twisted.internet.interfaces.IReactorTime) -- reactor used to get current time
Returns:

(boolean) whether reclaim succeeded or not

Reclaim a list of buildrequests

unclaimBuildRequests(brids)
Parameters:brids (list(integer)) -- list of buildrequest id to unclaim

Unclaim a list of buildrequests

completeBuildRequests(brids, results, complete_at=None, _reactor=twisted.internet.reactor)
Parameters:
  • brids (list(integer)) -- list of buildrequest id to complete
  • results (integer) -- the results of the buildrequest (see Build Result Codes)
  • complete_at (datetime) -- date and time when the buildrequest is completed
  • _reactor (twisted.internet.interfaces.IReactorTime) -- reactor used to get current time, if complete_at is None

Complete a list of buildrequest with the results status

unclaimExpiredRequests(old, _reactor=twisted.internet.reactor)
Parameters:
  • old (integer) -- time in seconds considered for getting unclaimed buildrequests
  • _reactor (twisted.internet.interfaces.IReactorTime) -- reactor used to get current time

Unclaim the previously claimed buildrequests that are older than old seconds and that were never completed

Endpoints

path: /builders/{builderid}/buildrequests
Path Keys:builderid (number) -- the ID of the builder

This path selects all buildrequests for a given builder (can return lots of data!)

GET
returns
collection of buildrequest
path: /buildrequests
GET
returns
collection of buildrequest
path: /buildrequests/{buildrequestid}
Path Keys:buildrequestid (number) -- the id of the buildrequest
GET
returns
collection of buildrequest
POST with method: /buildrequests/{buildrequestid}:cancel
Body keys:
  • method (string) -- must be cancel
  • reason (string) -- The reason why the buildrequest was cancelled

buildset

resource type: buildset
Attributes:
  • bsid (integer) -- the ID of this buildset
  • complete (boolean) -- true if all of the build requests in this buildset are complete
  • complete_at? (integer) -- the time this buildset was completed, or None if not complete
  • external_idstring? (string) -- an identifier that external applications can use to identify a submitted buildset; can be None
  • parent_buildid? (integer) -- optional build id that is the parent for this buildset
  • parent_relationship? (string) -- relationship identifier for the parent, this is is configured relationship between the parent build, and the childs buildsets
  • reason (string) -- the reason this buildset was scheduled
  • results? (integer) -- the results of the buildset (see Build Result Codes), or None if not complete
  • sourcestamps[] (sourcestamp) -- the sourcestamps for this buildset; each element is a valid sourcestamp entity
  • submitted_at (integer) -- the time this buildset was submitted

A buildset gathers build requests that were scheduled at the same time, and which share a source stamp, properties, and so on.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.buildsets.Buildset
addBuildset(scheduler=None, sourcestamps=[], reason='', properties={}, builderids=[], external_idstring=None, parent_buildid=None, parent_relationship=None)
Parameters:
  • scheduler (string) -- the name of the scheduler creating this buildset
  • sourcestamps (list) -- sourcestamps for the new buildset; see below
  • reason (unicode) -- the reason for this build
  • properties (dictionary with unicode keys and (source, property value) values) -- properties to set on this buildset
  • builderids (list) -- names of the builderids for which build requests should be created
  • external_idstring (unicode) -- arbitrary identifier to recognize this buildset later
  • parent_buildid (int) -- optional build id that is the parent for this buildset
  • parent_relationship (unicode) -- relationship identifier for the parent, this is is configured relationship between the parent build, and the childs buildsets
Returns:

(buildset id, dictionary mapping builder ids to build request ids) via Deferred

Create a new buildset and corresponding buildrequests based on the given parameters. This is the low-level interface for scheduling builds.

Each sourcestamp in the list of sourcestamps can be given either as an integer, assumed to be a sourcestamp ID, or a dictionary of keyword arguments to be passed to findSourceStampId.

maybeBuildsetComplete(bsid)
Parameters:bsid (integer) -- buildset that may be complete
Returns:Deferred

This method should be called when a build request is finished. It checks the given buildset to see if all of its buildrequests are finished. If so, it updates the status of the buildset and send the appropriate messages.

Endpoints

path: /buildsets

this path selects all buildsets

GET
returns
collection of buildset
path: /buildsets/{bsid}
Path Keys:bsid (identifier) -- the id of the buildset

this path selects a buildset by id

GET
returns
collection of buildset

change

resource type: change
Attributes:
  • changeid (integer) -- the ID of this change
  • author (string) -- the author of the change in "name", "name <email>" or just "email" (with @) format
  • branch? (string) -- branch on which the change took place, or none for the "default branch", whatever that might mean
  • category? (string) -- user-defined category of this change, or none
  • codebase (string) -- codebase in this repository
  • comments (string) -- user comments for this change (aka commit)
  • files[] (string) -- list of source-code filenames changed
  • parent_changeids[] (integer) -- The ID of the parents. The data api allow for several parents, but the core buildbot does not yet support
  • project (string) -- user-defined project to which this change corresponds
  • properties (sourcedproperties) -- user-specified properties for this change, represented as an object mapping keys to tuple (value, source)
  • repository (string) -- repository where this change occurred
  • revision? (string) -- revision for this change, or none if unknown
  • revlink? (string) -- link to a web view of this change
  • sourcestamp (sourcestamp) -- the sourcestamp resouce for this change
  • when_timestamp (integer) -- time of the change

A change resource represents a change to the source code monitored by Buildbot.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.changes.Change
addChange(files=None, comments=None, author=None, revision=None, when_timestamp=None, branch=None, category=None, revlink='', properties={}, repository='', codebase=None, project='', src=None)
Parameters:
  • files (list of unicode strings) -- a list of filenames that were changed
  • comments (unicode) -- user comments on the change
  • author (unicode) -- the author of this change
  • revision (unicode) -- the revision identifier for this change
  • when_timestamp (integer) -- when this change occurred (seconds since the epoch), or the current time if None
  • branch (unicode) -- the branch on which this change took place
  • category (unicode) -- category for this change
  • revlink (string) -- link to a web view of this revision
  • properties (dictionary with unicode keys and simple values (JSON-able)) -- properties to set on this change. Note that the property source is not included in this dictionary.
  • repository (unicode) -- the repository in which this change took place
  • project (unicode) -- the project this change is a part of
  • src (unicode) -- source of the change (vcs or other)
Returns:

the ID of the new change, via Deferred

Add a new change to Buildbot. This method is the interface between change sources and the rest of Buildbot.

All parameters should be passed as keyword arguments.

All parameters labeled 'unicode' must be unicode strings and not bytestrings. Filenames in files, and property names, must also be unicode strings. This is tested by the fake implementation.

Endpoints

path: /builds/{buildid}/changes
Path Keys:buildid (number) -- the id of the build

This path selects all changes tested by a build

GET
returns
collection of change
path: /changes

This path selects all changes. On a reasonabily loaded master, this can quickly return a very large result, taking minutes to process. A specific query configuration is optimized which allows to get the recent changes: order:-changeid&limit=<n>

GET
returns
collection of change
path: /changes/{changeid}
Path Keys:changeid (number) -- the id of a change

this path selects one change by id

GET
returns
collection of change
path: /sourcestamps/{ssid}/changes
Path Keys:ssid (number) -- the id of the sourcestamp

This path selects all changes associated to one sourcestamp

GET
returns
collection of change

changesource

resource type: changesource
Attributes:
  • changesourceid (integer) -- the ID of this changesource
  • master? (master) -- the master on which this worker is running, or None if it is inactive
  • name (string) -- name of this changesource

A changesource generates change objects, for example in response to an update in some repository. A particular changesource (by name) runs on at most one master at a time.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.changesources.ChangeSource
findChangeSourceId(name)
Parameters:name (string) -- changesource name
Returns:changesource ID via Deferred

Get the ID for the given changesource name, inventing one if necessary.

trySetChangeSourceMaster(changesourceid, masterid)
Parameters:
  • changesourceid (integer) -- changesource ID to try to claim
  • masterid (integer) -- this master's master ID
Returns:

True or False, via Deferred

Try to claim the given scheduler for the given master and return True if the scheduler is to be activated on that master.

Endpoints

path: /changesources

This path selects all changesource.

GET
returns
collection of changesource
path: /changesources/{changesourceid}
Path Keys:changesourceid (number) -- the id of a changesource

This path selects one changesource given its id.

GET
returns
collection of changesource
path: /masters/{masterid}/changesources
Path Keys:masterid (number) -- the id of the master

This path selects all changesources for a given master

GET
returns
collection of changesource
path: /masters/{masterid}/changesources/{changesourceid}
Path Keys:masterid (number) -- the id of the master

This path selects one changesource by id for a given master

GET
returns
collection of changesource

forcescheduler

resource type: forcescheduler
Attributes:
  • all_fields[] (object) --
  • builder_names[] (identifier) -- names of the builders that this scheduler can trigger
  • button_name (string) -- label of the button to use in the UI
  • label (string) -- label of this scheduler to be displayed in the ui
  • name (identifier) -- name of this scheduler

A forcescheduler initiates builds, via a formular in the web UI. At the moment, forceschedulers must be defined on all the masters where a web ui is configured. A particular forcescheduler runs on the master where the web request was sent.

Note

This datatype and associated endpoints will be deprecated when bug #2673 will be resolved.

Endpoints

path: /builders/{builderid}/forceschedulers
Path Keys:builderid (number) -- the ID of the builder

This path selects all force-schedulers for a given builder

GET
returns
collection of forcescheduler
path: /forceschedulers

This path selects all forceschedulers.

GET
returns
collection of forcescheduler
path: /forceschedulers/{schedulername}
Path Keys:schedulername (identifier) -- the name of a scheduler

This path selects all changesource.

GET
returns
collection of forcescheduler
POST with method: /forceschedulers/{schedulername}:force
Body keys:
  • method (string) -- must be force
  • owner (string) -- The user who wants to create the buildrequest
  • [] -- content of the forcescheduler parameter is dependent on the configuration of the forcescheduler

identifier

resource type: identifier

Logs

resource type: log
Attributes:
  • complete (boolean) -- true if this log is complete and will not generate additional logchunks
  • logid (integer) -- the unique ID of this log
  • name (string) -- the name of this log (e.g., err.html)
  • num_lines (integer) -- total number of line of this log
  • slug (identifier) -- the "slug", suitable for use in a URL, of this log (e.g., err_html)
  • stepid (integer) -- id of the step containing this log
  • type (identifier) -- log type, identified by a single ASCII letter; see logchunk for details.

example

{
    "logid": 60,
    "name": "stdio",
    "slug": "stdio",
    "stepid": 50,
    "complete": false,
    "num_lines": 0,
    "type": "s"
}

A log represents a stream of textual output from a step. The actual output is encoded as a sequence of logchunk resources. In-progress logs append logchunks as new data is added to the end, and event subscription allows a client to "follow" the log.

Each log has a "slug" which is unique within the step, and which can be used in paths. The slug is generated by addLog based on the name, using forceIdentifier and incrementIdentifier to guarantee uniqueness.

Todo

event: build.$buildid.step.$number.log.$logid.newlog

The log has just started. Logs are started when they are created, so this also indicates the creation of a new log.

event: build.$buildid.step.$number.log.$logid.complete

The log is complete.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.logs.Log
addLog(stepid, name, type)
Parameters:
  • stepid (integer) -- stepid containing this log
  • name (string) -- name for the log
Raises:

KeyError -- if a log by the given name already exists
Returns:

logid via Deferred

Create a new log and return its ID. The name need not be unique. This method will generate a unique slug based on the name.

appendLog(logid, content):
Parameters:
  • logid (integer) -- the log to which content should be appended
  • content (unicode) -- the content to append

Append the given content to the given log. The content must end with a newline. All newlines in the content should be UNIX-style (\n).

finishLog(logid)
Parameters:logid (integer) -- the log to finish

Mark the log as complete.

compressLog(logid)
Parameters:logid (integer) -- the log to compress

Compress the given log, after it is finished. This operation may take some time.

Endpoints

path: /builders/{builderid}/builds/{build_number}/steps/{step_name}/logs
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_name (identifier) -- the slug name of the step

This path selects all logs for the given step.

GET
returns
collection of log
path: /builders/{builderid}/builds/{build_number}/steps/{step_name}/logs/{log_slug}
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_name (identifier) -- the slug name of the step
  • log_slug (identifier) -- the slug name of the log
GET
returns
collection of log
path: /builders/{builderid}/builds/{build_number}/steps/{step_number}/logs
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_number (number) -- the number of the step

This path selects all log of a a specific step

GET
returns
collection of log
path: /builders/{builderid}/builds/{build_number}/steps/{step_number}/logs/{log_slug}
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_number (number) -- the number of the step
  • log_slug (identifier) -- the slug name of the log

This path selects one log of a a specific step

GET
returns
collection of log
path: /builds/{buildid}/steps/{step_number_or_name}/logs
Path Keys:
  • buildid (number) -- the id of the build
  • | number step_number_or_name (identifier) -- the name or number of the step

This path selects all logs of a step of a build

GET
returns
collection of log
path: /builds/{buildid}/steps/{step_number_or_name}/logs/{log_slug}
Path Keys:
  • buildid (number) -- the id of the build
  • | number step_number_or_name (identifier) -- the name or number of the step
  • log_slug (identifier) -- the slug name of the log

This path selects one log of a a specific step

GET
returns
collection of log
path: /logs/{logid}
Path Keys:logid (number) -- the id of the log

This path selects one log

GET
returns
collection of log
path: /steps/{stepid}/logs
Path Keys:stepid (number) -- the id of the step

This path selects all logs for the given step.

GET
returns
collection of log
path: /steps/{stepid}/logs/{log_slug}
Path Keys:
  • stepid (number) -- the id of the step
  • log_slug (identifier) -- the slug name of the log
GET
returns
collection of log

logchunk

resource type: logchunk
Attributes:
  • content (string) -- content of the chunk
  • firstline (integer) -- zero-based line number of the first line in this chunk
  • logid (integer) -- the ID of log containing this chunk

A logchunk represents a contiguous sequence of lines in a logfile. Logs are not individually addressable in the data API; instead, they must be requested by line number range. In a strict REST sense, many logchunk resources will contain the same line.

The chunk contents is represented as a single unicode string. This string is the concatenation of each newline terminated-line.

Each log has a type, as identified by the "type" field of the corresponding log. While all logs are sequences of unicode lines, the type gives additional information fo interpreting the contents. The defined types are:

  • t -- text, a simple sequence of lines of text
  • s -- stdio, like text but with each line tagged with a stream
  • h -- HTML, represented as plain text

In the stream type, each line is prefixed by a character giving the stream type for that line. The types are i for input, o for stdout, e for stderr, and h for header. The first three correspond to normal UNIX standard streams, while the header stream contains metadata produced by Buildbot itself.

The offset and limit parameters can be used to select the desired lines. These are specified as query parameters via the REST interface, or as arguments to the get method in Python. The result will begin with line offset (so the resulting firstline will be equal to the given offset), and will contain up to limit lines.

Following example will get the first 100 lines of a log:

from buildbot.data import resultspec
first_100_lines = yield self.master.data.get(("logs", log['logid'], "contents"),
    resultSpec=resultspec.ResultSpec(limit=100))

Following example will get the last 100 lines of a log:

from buildbot.data import resultspec
last_100_lines = yield self.master.data.get(("logs", log['logid'], "contents"),
    resultSpec=resultspec.ResultSpec(offset=log['num_lines']-100))

Note

There is no event for a new chunk. Instead, the log resource is updated when new chunks are added, with the new number of lines. Consumers can then request those lines, if desired.

Update Methods

Log chunks are updated via log.

Endpoints

path: /builders/{builderid}/builds/{build_number}/steps/{step_name}/logs/{log_slug}/contents
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_name (identifier) -- the slug name of the step
  • log_slug (identifier) -- the slug name of the log
GET
returns
collection of logchunk
path: /builders/{builderid}/builds/{build_number}/steps/{step_number}/logs/{log_slug}/contents
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_number (number) -- the number of the step
  • log_slug (identifier) -- the slug name of the log
GET
returns
collection of logchunk
path: /builds/{buildid}/steps/{step_number_or_name}/logs/{log_slug}/contents
Path Keys:
  • buildid (number) -- the id of the build
  • | number step_number_or_name (identifier) -- the name or number of the step
  • log_slug (identifier) -- the slug name of the log
GET
returns
collection of logchunk
path: /logs/{logid}/contents
Path Keys:logid (number) -- the id of the log
GET
returns
collection of logchunk
path: /steps/{stepid}/logs/{log_slug}/contents
Path Keys:
  • stepid (number) -- the id of the step
  • log_slug (identifier) -- the slug name of the log
GET
returns
collection of logchunk

master

resource type: master
Attributes:
  • active (boolean) -- true if the master is active
  • last_active (date) -- time this master was last marked active
  • masterid (integer) -- the ID of this master
  • name (string) -- master name (in the form "hostname:basedir")

This resource type describes buildmasters in the buildmaster cluster.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.masters.Master
masterActive(name, masterid)
Parameters:
  • name (unicode) -- the name of this master (generally hostname:basedir)
  • masterid (integer) -- this master's master ID
Returns:

Deferred

Mark this master as still active. This method should be called at startup and at least once per minute. The master ID is acquired directly from the database early in the master startup process.

expireMasters()
Returns:Deferred

Scan the database for masters that have not checked in for ten minutes. This method should be called about once per minute.

masterStopped(name, masterid)
Parameters:
  • name (unicode) -- the name of this master
  • masterid (integer) -- this master's master ID
Returns:

Deferred

Mark this master as inactive. Masters should call this method before completing an expected shutdown, and on startup. This method will take care of deactivating or removing configuration resources like builders and schedulers as well as marking lost builds and build requests for retry.

Endpoints

path: /builders/{builderid}/masters
Path Keys:builderid (number) -- the ID of the builder

This path selects all masters supporting a given builder

GET
returns
collection of master
path: /builders/{builderid}/{masterid}
Path Keys:
  • builderid (number) -- the ID of the builder
  • masterid (number) -- the id of the master

This path selects a master by id filtered by given builderid

GET
returns
collection of master
path: /masters

This path selects all masters

GET
returns
collection of master
path: /masters/{masterid}
Path Keys:masterid (number) -- the id of the master

This path selects one master given its id

GET
returns
collection of master

patch

resource type: patch
Attributes:
  • patchid (integer) -- the unique ID of this patch
  • body (string) -- patch body as a binary string
  • level (integer) -- patch level - the number of directory names to strip from filenames in the patch
  • subdir (string) -- subdirectory in which patch should be applied
  • author? (string) -- patch author, or None
  • comment? (string) -- patch comment, or None

This resource type describes a patch. Patches have unique IDs, but only appear embedded in sourcestamps, so those IDs are not especially useful.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.patches.Patch

(no update methods)

scheduler

resource type: scheduler
Attributes:
  • master? (master) -- the master on which this scheduler is running, or None if it is inactive
  • name (string) -- name of this scheduler
  • schedulerid (integer) -- the ID of this scheduler

A scheduler initiates builds, often in response to changes from change sources. A particular scheduler (by name) runs on at most one master at a time.

Note

This data type and associated endpoints is planned to be merged with forcescheduler data type when bug #2673 will be resolved.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.schedulers.Scheduler
findSchedulerId(name)
Parameters:name (string) -- scheduler name
Returns:scheduler ID via Deferred

Get the ID for the given scheduler name, inventing one if necessary.

trySetSchedulerMaster(schedulerid, masterid)
Parameters:
  • schedulerid (integer) -- scheduler ID to try to claim
  • masterid (integer) -- this master's master ID
Returns:

True or False, via Deferred

Try to claim the given scheduler for the given master and return True if the scheduler is to be activated on that master.

Endpoints

path: /masters/{masterid}/schedulers
Path Keys:masterid (number) -- the id of the master

This path selects all schedulers for a given master

GET
returns
collection of scheduler
path: /masters/{masterid}/schedulers/{schedulerid}
Path Keys:
  • masterid (number) -- the id of the master
  • schedulerid (number) -- the id of the scheduler

This path selects one scheduler by id for a given master

GET
returns
collection of scheduler
path: /schedulers

This path selects all schedulers

GET
returns
collection of scheduler
path: /schedulers/{schedulerid}
Path Keys:schedulerid (number) -- the id of the scheduler

This path selects one scheduler by id

GET
returns
collection of scheduler

sourcedproperties

resource type: sourcedproperties
Attributes:[] (object) -- Each key of this map is the name of a defined property The value consist on a couple (source, value)

user-specified properties for this change, represented as an object mapping keys to tuple (value, source)

Properties are present in several data resources, but have a separate endpoints, because they can represent a large dataset.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.properties.Properties
setBuildProperty(buildid, name, value, source)
Parameters:
  • buildid (integer) -- build ID
  • name (unicode) -- Name of the property to set
  • value (Any JSON-able type is accepted (lists, dicts, strings and numbers)) -- Value of the property
  • source (unicode) -- Source of the property to set

Set a build property. If no property with that name exists in that build, a new property will be created.

setBuildProperties(buildid, props)
Parameters:
  • buildid (integer) -- build ID
  • props (IProperties) -- Name of the property to set

Synchronise build properties with the db. This sends only one event in the end of the sync, and only if properties changed. The event contains only the updated properties, for network efficiency reasons.

Endpoints

path: /builds/{buildid}/properties
Path Keys:buildid (number) -- the id of the build

This path selects all properties of a build

GET
returns
collection of sourcedproperties
path: /buildsets/{bsid}/properties
Path Keys:bsid (identifier) -- the id of the buildset

This path selects all properties of a buildset. Buildset properties is part of the initial properties of a build.

GET
returns
collection of sourcedproperties

sourcestamp

resource type: sourcestamp
Attributes:
  • ssid (integer) --

    the ID of this sourcestamp

    Note

    For legacy reasons, the abbreviated name ssid is used instead of canonical sourcestampid. This might change in the future (bug #3509).

  • branch? (string) -- code branch, or none for the "default branch", whatever that might mean
  • codebase (string) -- revision for this sourcestamp, or none if unknown
  • created_at (date) -- the timestamp when this sourcestamp was created
  • patch? (patch) -- the patch for this sourcestamp, or none
  • project (string) -- user-defined project to which this sourcestamp corresponds
  • repository (string) -- repository where this sourcestamp occurred
  • revision? (string) -- revision for this sourcestamp, or none if unknown

A source stamp represents a particular version of the source code. Absolute sourcestamps specify this completely, while relative sourcestamps (with revision = None) specify the latest source at the current time. Source stamps can also have patches; such stamps describe the underlying revision with the given patch applied.

Note that, depending on the underlying version-control system, the same revision may describe different code in different branches (e.g., SVN) or may be independent of the branch (e.g., Git).

The created_at timestamp can be used to indicate the first time a sourcestamp was seen by Buildbot. This provides a reasonable default ordering for sourcestamps when more reliable information is not available.

Endpoints

path: /sourcestamps

This path selects all sourcestamps (can return lots of data!)

GET
returns
collection of sourcestamp
path: /sourcestamps/{ssid}
Path Keys:ssid (number) -- the id of the sourcestamp

This path selects one sourcestamp by id

GET
returns
collection of sourcestamp

spec

resource type: spec
Attributes:
  • path (string) --
  • plural (string) --
  • type (string) --
  • type_spec (object) --

Endpoints

path: /application.spec
GET
returns
collection of spec

step

resource type: step
Attributes:
  • stepid (integer) -- the unique ID of this step
  • buildid (integer) -- id of the build containing this step
  • complete (boolean) -- true if this step is complete
  • complete_at? (date) -- time at which this step was complete, or None if it's still running
  • hidden (boolean) -- true if the step should not be displayed
  • name (identifier) -- the step name, unique within the build
  • number (integer) -- the number of this step (sequential within the build)
  • results? (integer) -- the results of the step (see Build Result Codes), or None if not complete
  • started_at? (date) -- time at which this step started, or None if it hasn't started yet
  • state_string (string) -- a string giving detail on the state of the build. The first is usually one word or phrase; the remainder are sized for one-line display.
  • urls[] -- a list of URLs associated with this step.

This resource type describes a step in a build. Steps have unique IDs, but are most commonly accessed by name in the context of their containing builds.

Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.steps.Step
newStep(buildid, name)
Parameters:
  • buildid (integer) -- buildid containing this step
  • name (50-character identifier) -- name for the step
Returns:

(stepid, number, name) via Deferred

Create a new step and return its ID, number, and name. Note that the name may be different from the requested name, if that name was already in use. The state strings for the new step will be set to 'pending'.

startStep(stepid)
Parameters:stepid (integer) -- the step to modify

Start the step.

setStepStateString(stepid, state_string)
Parameters:
  • stepid (integer) -- the step to modify
  • state_string (unicode) -- new state strings for this step

Replace the existing state string for a step with a new list.

addStepURL(stepid, name, url):
Parameters:
  • stepid (integer) -- the step to modify
  • name (string) -- the url name
  • url (string) -- the actual url
Returns:

None via deferred

Add a new url to a step. The new url is added to the list of urls.

finishStep(stepid, results, hidden)
Parameters:
  • stepid (integer) -- the step to modify
  • results (integer) -- the step's results
  • hidden (boolean) -- true if the step should not be displayed

Mark the step as finished at the current time, with the given results.

Endpoints

path: /builders/{builderid}/builds/{build_number}/steps
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder

This path selects all steps for the given build.

GET
returns
collection of step
path: /builders/{builderid}/builds/{build_number}/steps/{step_name}
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_name (identifier) -- the slug name of the step

This path selects a specific step for the given build.

GET
returns
collection of step
path: /builders/{builderid}/builds/{build_number}/steps/{step_number}
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_number (number) -- the number of the step

This path selects a specific step given its step number

GET
returns
collection of step
path: /builds/{buildid}/steps
Path Keys:buildid (number) -- the id of the build

This path selects all steps of a build

GET
returns
collection of step
path: /builds/{buildid}/steps/{step_number_or_name}
Path Keys:
  • buildid (number) -- the id of the build
  • | number step_number_or_name (identifier) -- the name or number of the step

This path selects one step of a build

GET
returns
collection of step

worker

resource type: worker
Attributes:
  • workerid (integer) -- the ID of this worker
  • configured_on[] -- list of builders on masters this worker is configured on
  • connected_to[] -- list of masters this worker is attached to
  • name (string) -- the name of the worker
  • workerinfo (object) --

    information about the worker.

    The worker information can be any JSON-able object. In practice, it contains the following keys, based on information provided by the worker:

    • admin (the admin information)
    • host (the name of the host)
    • access_uri (the access URI)
    • version (the version on the worker)

A worker resource represents a worker to the source code monitored by Buildbot.

The contents of the connected_to and configured_on attributes are sensitive to the context of the request. If a builder or master is specified in the path, then only the corresponding connections and configurations are included in the result.

Endpoints

path: /builders/{builderid}/workers
Path Keys:builderid (number) -- the ID of the builder

This path selects all workers configured for a given builder

GET
returns
collection of worker
path: /builders/{builderid}/workers/{name}
Path Keys:
  • builderid (number) -- the ID of the builder
  • name (identifier) -- the name of the worker

This path selects a worker by name filtered by given builderid

GET
returns
collection of worker
path: /builders/{builderid}/workers/{workerid}
Path Keys:
  • builderid (number) -- the ID of the builder
  • workerid (number) -- the id of the worker

This path selects a worker by id filtered by given builderid

GET
returns
collection of worker
path: /masters/{masterid}/builders/{builderid}/workers
Path Keys:
  • masterid (number) -- the id of the master
  • builderid (number) -- the id of the builder

This path selects all workers for a given builder and a given master

GET
returns
collection of worker
path: /masters/{masterid}/builders/{builderid}/workers/{name}
Path Keys:
  • masterid (number) -- the id of the master
  • builderid (number) -- the id of the builder
  • name (identifier) -- the name of the worker

This path selects one workers by name for a given builder and a given master

GET
returns
collection of worker
path: /masters/{masterid}/builders/{builderid}/workers/{workerid}
Path Keys:
  • masterid (number) -- the id of the master
  • builderid (number) -- the id of the builder
  • workerid (number) -- the id of the worker

This path selects one workers by name for a given builder and a given master

GET
returns
collection of worker
path: /masters/{masterid}/workers
Path Keys:masterid (number) -- the id of the master

This path selects all workers for a given master

GET
returns
collection of worker
path: /masters/{masterid}/workers/{name}
Path Keys:
  • masterid (number) -- the id of the master
  • name (identifier) -- the name of the worker

This path selects one worker by name for a given master

GET
returns
collection of worker
path: /masters/{masterid}/workers/{workerid}
Path Keys:
  • masterid (number) -- the id of the master
  • workerid (number) -- the id of the worker

This path selects one worker by id for a given master

GET
returns
collection of worker
path: /workers

this path selects all workers

GET
returns
collection of worker
path: /workers/{name_or_id}
Path Keys:| number name_or_id (identifier) -- the name or id of a worker

this path selects worker by name or id

GET
returns
collection of worker

Raw endpoints

Raw endpoints allow to download content in their raw format (i.e. not within a json glue). The content-disposition http header is set, so that the browser knows which file to store the content to.

path: /builders/{builderid}/builds/{build_number}/steps/{step_name}/logs/{log_slug}/raw
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_name (identifier) -- the slug name of the step
  • log_slug (identifier) -- the slug name of the log

This endpoint allows to get the raw logs for downloading into a file. This endpoint does not provide paging capabilities. For stream log types, the type line header characters are dropped. 'text/plain' is used as the mime type except for html logs, where 'text/html' is used. The 'slug' is used as the filename for the resulting download. Some browsers are appending ".txt" or ".html" to this filename according to the mime-type.

path: /builders/{builderid}/builds/{build_number}/steps/{step_number}/logs/{log_slug}/raw
Path Keys:
  • builderid (number) -- the ID of the builder
  • build_number (number) -- the number of the build within the builder
  • step_number (number) -- the number of the step
  • log_slug (identifier) -- the slug name of the log

This path downloads the whole log

path: /builds/{buildid}/steps/{step_number_or_name}/logs/{log_slug}/raw
Path Keys:
  • buildid (number) -- the id of the build
  • | number step_number_or_name (identifier) -- the name or number of the step
  • log_slug (identifier) -- the slug name of the log

This path downloads the whole log

path: /logs/{logid}/raw
Path Keys:logid (number) -- the id of the log

This path downloads the whole log

path: /steps/{stepid}/logs/{log_slug}/raw
Path Keys:
  • stepid (number) -- the id of the step
  • log_slug (identifier) -- the slug name of the log

This path downloads the whole log

Raml spec verbatim

Sometimes Raml is just clearer than formatted text.

#%RAML 1.0
title: Buildbot Web API
version: v2
mediaType: application/json
traits:
    bbget:
        responses:
            200:
                body:
                    application/json:
                        type: responseObjects.libraries.types.<<bbtype>>
            404:
                body:
                    text/plain:
                        example: "not found"
    bbpost:
        body:
            type: <<reqtype>>
        responses:
            200:
                body:
                    application/json:
                        type: <<resptype>>
            404:
                body:
                    text/plain:
                        example: "not found"
    bbgetraw:
        responses:
            200:
                headers:
                    content-disposition:
                        description: content disposition header allows browser to save log file with proper filename
                        example: attachment; filename=stdio
                body:
                    text/html:
                        description: "html data if the object is html"
                    text/plain:
                        description: "plain text data if the object is text"

types:
    build: !include types/build.raml
    builder: !include types/builder.raml
    buildrequest: !include types/buildrequest.raml
    buildset: !include types/buildset.raml
    worker: !include types/worker.raml
    change: !include types/change.raml
    changesource: !include types/changesource.raml
    forcescheduler: !include types/forcescheduler.raml
    identifier: !include types/identifier.raml
    log: !include types/log.raml
    logchunk: !include types/logchunk.raml
    master: !include types/master.raml
    rootlink: !include types/rootlink.raml
    scheduler: !include types/scheduler.raml
    sourcedproperties: !include types/sourcedproperties.raml
    sourcestamp: !include types/sourcestamp.raml
    patch: !include types/patch.raml
    spec: !include types/spec.raml
    step: !include types/step.raml
/:
    get:
        is:
        - bbget: {bbtype: rootlink}
/application.spec:
    get:
        is:
        - bbget: {bbtype: spec}
/builders:
    description: This path selects all builders
    get:
        is:
        - bbget: {bbtype: builder}
    /{builderid}:
        uriParameters:
            builderid:
                type: number
                description: the ID of the builder
        description: This path selects a builder by builderid
        get:
            is:
            - bbget: {bbtype: builder}
        /forceschedulers:
            description: This path selects all force-schedulers for a given builder
            get:
                is:
                - bbget: {bbtype: forcescheduler}
        /buildrequests:
            description: This path selects all buildrequests for a given builder (can return lots of data!)
            get:
                is:
                - bbget: {bbtype: buildrequest}
        /builds:
            description: This path selects all builds for a builder (can return lots of data!)
            get:
                is:
                - bbget: {bbtype: build}
            /{build_number}:
                uriParameters:
                    build_number:
                        type: number
                        description: the number of the build within the builder
                description: This path selects a specific build by builderid, buildnumber
                get:
                    is:
                    - bbget: {bbtype: build}
                /actions/stop:
                    post:
                        description: |
                            stops one build.
                        body:
                            application/json:
                                properties:
                                    reason:
                                        type: string
                                        required: false
                                        description: The reason why the build was stopped
                                    results:
                                        type: integer
                                        required: false
                                        description: optionally results value override (default CANCELLED)
                /actions/rebuild:
                    post:
                        description: |
                            rebuilds one build.
                        body:
                            application/json:
                                description: no parameter are needed
                /steps:
                    description: This path selects all steps for the given build.
                    get:
                        is:
                        - bbget: {bbtype: step}
                    /{step_name}:
                        uriParameters:
                            step_name:
                                type: identifier
                                description: the slug name of the step
                        description: This path selects a specific step for the given build.
                        get:
                            is:
                            - bbget: {bbtype: step}
                        /logs:
                            description: This path selects all logs for the given step.
                            get:
                                is:
                                - bbget: {bbtype: log}
                            /{log_slug}:
                                uriParameters:
                                    log_slug:
                                        type: identifier
                                        description: the slug name of the log
                                get:
                                    description: |
                                        This path selects a specific log in the given step.
                                    is:
                                    - bbget: {bbtype: log}
                                /contents:
                                    get:
                                        description: |
                                            This path selects chunks from a specific log in the given step.
                                        is:
                                        - bbget: {bbtype: logchunk}
                                /raw:
                                    get:
                                        description: |
                                            This endpoint allows to get the raw logs for downloading into a file.
                                            This endpoint does not provide paging capabilities.
                                            For stream log types, the type line header characters are dropped.
                                            'text/plain' is used as the mime type except for html logs, where 'text/html' is used.
                                            The 'slug' is used as the filename for the resulting download. Some browsers are appending ``".txt"`` or ``".html"`` to this filename according to the mime-type.
                                        is:
                                        - bbgetraw:

                    /{step_number}:
                        uriParameters:
                            step_number:
                                type: number
                                description: the number of the step
                        description: This path selects a specific step given its step number
                        get:
                            is:
                            - bbget: {bbtype: step}
                        /logs:
                            description: This path selects all log of a a specific step
                            get:
                                is:
                                - bbget: {bbtype: log}
                            /{log_slug}:
                                uriParameters:
                                    log_slug:
                                        type: identifier
                                        description: the slug name of the log
                                description: This path selects one log of a a specific step
                                get:
                                    is:
                                    - bbget: {bbtype: log}
                                /contents:
                                    get:
                                        description: |
                                            This path selects chunks from a specific log in the given step.
                                        is:
                                        - bbget: {bbtype: logchunk}
                                /raw:
                                    get:
                                        description: |
                                            This path downloads the whole log
                                        is:
                                        - bbgetraw:

        /workers:
            description: |
                This path selects all workers configured for a given builder
            get:
                is:
                - bbget: {bbtype: worker}
            /{name}:
                description: |
                    This path selects a worker by name filtered by given builderid
                uriParameters:
                    name:
                        type: identifier
                        description: the name of the worker
                get:
                    is:
                    - bbget: {bbtype: worker}
            /{workerid}:
                description: |
                    This path selects a worker by id filtered by given builderid
                uriParameters:
                    workerid:
                        type: number
                        description: the id of the worker
                get:
                    is:
                    - bbget: {bbtype: worker}
        /masters:
            description: |
                This path selects all masters supporting a given builder
            get:
                is:
                - bbget: {bbtype: master}

        /{masterid}:
            uriParameters:
                masterid:
                    type: number
                    description: the id of the master
            description: |
                This path selects a master by id filtered by given builderid
            get:
                is:
                - bbget: {bbtype: master}
/buildrequests:
    /{buildrequestid}:
        uriParameters:
            buildrequestid:
                type: number
                description: the id of the buildrequest
        get:
            is:
            - bbget: {bbtype: buildrequest}
        /builds:
            get:
                is:
                - bbget: {bbtype: build}
        /actions/cancel:
            post:
                description: |
                    Cancel one buildrequest.
                    If necessary, this will stop the builds generated by the buildrequest, including triggered builds.
                body:
                    application/json:
                        properties:
                            reason:
                                type: string
                                required: false
                                description: The reason why the buildrequest was cancelled
    get:
        is:
        - bbget: {bbtype: buildrequest}
/builds:
    get:
        is:
        - bbget: {bbtype: build}
    /{buildid}:
        description: |
            This path selects a build by id
        uriParameters:
            buildid:
                type: number
                description: the id of the build
        get:
            is:
            - bbget: {bbtype: build}
        /actions/stop:
            post:
                description: |
                    stops one build.
                body:
                    application/json:
                        properties:
                            reason:
                                type: string
                                required: false
                                description: The reason why the build was stopped
        /actions/rebuild:
            post:
                description: |
                    rebuilds one build.
                body:
                    application/json:
                        description: no parameter are needed
        /changes:
            description: |
                This path selects all changes tested by a build
            get:
                is:
                - bbget: {bbtype: change}
        /properties:
            description: |
                This path selects all properties of a build
            get:
                is:
                - bbget: {bbtype: sourcedproperties}
        /steps:
            description: |
                This path selects all steps of a build
            get:
                is:
                - bbget: {bbtype: step}
            /{step_number_or_name}:
                uriParameters:
                    step_number_or_name:
                        type: identifier | number
                        description: the name or number of the step
                description: |
                    This path selects one step of a build
                get:
                    is:
                    - bbget: {bbtype: step}
                /logs:
                    description: |
                        This path selects all logs of a step of a build
                    get:
                        is:
                        - bbget: {bbtype: log}
                    /{log_slug}:
                        uriParameters:
                            log_slug:
                                type: identifier
                                description: the slug name of the log
                        description: This path selects one log of a a specific step
                        get:
                            is:
                            - bbget: {bbtype: log}
                        /contents:
                            get:
                                description: |
                                    This path selects chunks from a specific log in the given step.
                                is:
                                - bbget: {bbtype: logchunk}
                        /raw:
                            get:
                                description: |
                                    This path downloads the whole log
                                is:
                                - bbgetraw:
/buildsets:
    description: this path selects all buildsets
    get:
        is:
        - bbget: {bbtype: buildset}
    /{bsid}:
        description: this path selects a buildset by id
        uriParameters:
            bsid:
                type: identifier
                description: the id of the buildset
        get:
            is:
            - bbget: {bbtype: buildset}
        /properties:
            description: |
                This path selects all properties of a buildset.
                Buildset properties is part of the initial properties of a build.
            get:
                is:
                - bbget: {bbtype: sourcedproperties}
/workers:
    description: this path selects all workers
    get:
        is:
        - bbget: {bbtype: worker}
    /{name_or_id}:
        description: this path selects worker by name or id
        uriParameters:
            name_or_id:
                type: identifier | number
                description: the name or id of a worker
        get:
            is:
            - bbget: {bbtype: worker}

/changes:
    description: |
        This path selects **all** changes.
        On a reasonabily loaded master, this can quickly return a very large result, taking minutes to process.
        A specific query configuration is optimized which allows to get the recent changes: ``order:-changeid&limit=<n>``
    get:
        is:
        - bbget: {bbtype: change}
    /{changeid}:
        description: this path selects one change by id
        uriParameters:
            changeid:
                type: number
                description: the id of a change
        get:
            is:
            - bbget: {bbtype: change}

/changesources:
    description: |
        This path selects all changesource.
    get:
        is:
        - bbget: {bbtype: changesource}
    /{changesourceid}:
        uriParameters:
            changesourceid:
                type: number
                description: the id of a changesource
        description: |
            This path selects one changesource given its id.
        get:
            is:
            - bbget: {bbtype: changesource}
/forceschedulers:
    description: |
        This path selects all forceschedulers.
    get:
        is:
        - bbget: {bbtype: forcescheduler}

    /{schedulername}:
        description: |
            This path selects all changesource.
        uriParameters:
            schedulername:
                type: identifier
                description: the name of a scheduler
        get:
            is:
            - bbget: {bbtype: forcescheduler}

        /actions/force:
            post:
                description: |
                    Triggers the forcescheduler
                body:
                    application/json:
                        properties:
                            owner:
                                type: string
                                required: false
                                description: The user who wants to create the buildrequest
                            '[]':
                                description: content of the forcescheduler parameter is dependent on the configuration of the forcescheduler
/logs/{logid}:
    uriParameters:
        logid:
            type: number
            description: the id of the log
    description: This path selects one log
    get:
        is:
        - bbget: {bbtype: log}
    /contents:
        get:
            description: |
                This path selects chunks from a specific log
            is:
            - bbget: {bbtype: logchunk}
    /raw:
        get:
            description: |
                This path downloads the whole log
            is:
            - bbgetraw:
/masters:
    description: This path selects all masters
    get:
        is:
        - bbget: {bbtype: master}
    /{masterid}:
        description: This path selects one master given its id
        uriParameters:
            masterid:
                type: number
                description: the id of the master
        get:
            is:
            - bbget: {bbtype: master}
        /builders:
            description: This path selects all builders of a given master
            get:
                is:
                - bbget: {bbtype: builder}
            /{builderid}:
                description: This path selects one builder by id of a given master
                uriParameters:
                    builderid:
                        type: number
                        description: the id of the builder
                get:
                    is:
                    - bbget: {bbtype: builder}
                /workers:
                    description: This path selects all workers for a given builder and a given master
                    get:
                        is:
                        - bbget: {bbtype: worker}
                    /{name}:
                        description: This path selects one workers by name for a given builder and a given master
                        uriParameters:
                            name:
                                type: identifier
                                description: the name of the worker
                        get:
                            is:
                            - bbget: {bbtype: worker}
                    /{workerid}:
                        description: This path selects one workers by name for a given builder and a given master
                        uriParameters:
                            workerid:
                                type: number
                                description: the id of the worker
                        get:
                            is:
                            - bbget: {bbtype: worker}
        /workers:
            description: This path selects all workers for a given master
            get:
                is:
                - bbget: {bbtype: worker}
            /{name}:
                description: This path selects one worker by name for a given master
                uriParameters:
                    name:
                        type: identifier
                        description: the name of the worker
                get:
                    is:
                    - bbget: {bbtype: worker}
            /{workerid}:
                description: This path selects one worker by id for a given master
                uriParameters:
                    workerid:
                        type: number
                        description: the id of the worker
                get:
                    is:
                    - bbget: {bbtype: worker}
        /changesources:
            description: This path selects all changesources for a given master
            get:
                is:
                - bbget: {bbtype: changesource}
            /{changesourceid}:
                description: This path selects one changesource by id for a given master
                get:
                    is:
                    - bbget: {bbtype: changesource}
        /schedulers:
            description: This path selects all schedulers for a given master
            get:
                is:
                - bbget: {bbtype: scheduler}
            /{schedulerid}:
                description: This path selects one scheduler by id for a given master
                uriParameters:
                    schedulerid:
                        type: number
                        description: the id of the scheduler
                get:
                    is:
                    - bbget: {bbtype: scheduler}
/schedulers:
    description: This path selects all schedulers
    get:
        is:
        - bbget: {bbtype: scheduler}
    /{schedulerid}:
        uriParameters:
            schedulerid:
                type: number
                description: the id of the scheduler
        description: This path selects one scheduler by id
        get:
            is:
            - bbget: {bbtype: scheduler}
/sourcestamps:
    description: This path selects all sourcestamps (can return lots of data!)
    get:
        is:
        - bbget: {bbtype: sourcestamp}
    /{ssid}:
        description: This path selects one sourcestamp by id
        uriParameters:
            ssid:
                type: number
                description: the id of the sourcestamp
        get:
            is:
            - bbget: {bbtype: sourcestamp}
        /changes:
            description: This path selects all changes associated to one sourcestamp
            get:
                is:
                - bbget: {bbtype: change}
/steps:
    /{stepid}:
        description: This path selects one step by id
        uriParameters:
            stepid:
                type: number
                description: the id of the step
        /logs:
            description: This path selects all logs for the given step.
            get:
                is:
                - bbget: {bbtype: log}
            /{log_slug}:
                uriParameters:
                    log_slug:
                        type: identifier
                        description: the slug name of the log
                get:
                    description: |
                        This path selects a specific log in the given step.
                    is:
                    - bbget: {bbtype: log}
                /contents:
                    get:
                        description: |
                            This path selects chunks from a specific log in the given step.
                        is:
                        - bbget: {bbtype: logchunk}
                /raw:
                    get:
                        description: |
                            This path downloads the whole log
                        is:
                        - bbgetraw: