Caution
Buildbot no longer supports Python 2.7 on the Buildbot master.
3.4.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.4.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 1.
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.
- 1
The JSON API defined by
status_json.py
in Buildbot-0.8.x is considered version 1, although its root path wasjson
, notapi/v1
.
3.4.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.4.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}
. 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).
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
Pagination¶
Collection responses may be paginated with the offset
and limit
query parameters.
The offset is the 0-based index of the first result to included, after filtering and sorting.
The limit is the maximum number of results to return.
Some resource types may impose a maximum on the limit parameter; be sure to check the resulting links to determine whether further data is available.
For example:
http://build.example.org/api/v2/buildrequest?order=builderid&limit=10
http://build.example.org/api/v2/buildrequest?order=builderid&offset=20&limit=10
3.4.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.4.1.5. Authentication¶
Authentication to the REST API is performed in the same manner as authentication to the main web interface. Once credentials have been established, a cookie will be set, which must be sent to the buildbot REST API with every request thereafter. For those buildbot instances using OAuth2 authentication providers, access tokens can be used for automated access. For example, GitHub’s personal access tokens can be used to access the buildbot as a github user without needing to store the username and password of the user. To use an OAuth2 access token, send a GET request to the /auth/login with the token URL parameter set to the access token that the OAuth2 provider has given you. A python example using requests is shown below, where we first authenticate with our OAuth2 access token, and then are able to request otherwise shielded endpoints:
import requests
s = requests.Session()
s.get("https://<buildbot_url>/auth/login", params={"token": OAUTH_TOKEN})
builders = s.get("https://<buildbot_url>/api/v2/builders").json()
3.4.1.6. 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_or_buildername}/builds
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
This path selects all builds for a builder (can return lots of data!)
GET
returns
collection
ofbuild
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
ofbuild
-
POST with method:
/builders/{builderid_or_buildername}/builds/{build_number} (method=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_or_buildername}/builds/{build_number} (method=rebuild)
- Body keys
method (string) – must be
rebuild
-
path:
/buildrequests/{buildrequestid}/builds
- Path Keys
buildrequestid (number) – the id of the buildrequest
GET
returns
collection
ofbuild
-
path:
/builds
GET
returns
collection
ofbuild
-
path:
/builds/{buildid}
- Path Keys
buildid (number) – the id of the build
This path selects a build by id
GET
returns
collection
ofbuild
-
POST with method:
/builds/{buildid} (method=stop)
- Body keys
method (string) – must be
stop
reason (string) – The reason why the build was stopped
-
POST with method:
/builds/{buildid} (method=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
-
path:
/builders/{builderid_or_buildername}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
This path selects a builder by builderid
GET
returns
-
path:
/masters/{masterid}/builders
- Path Keys
masterid (number) – the id of the master
This path selects all builders of a given master
GET
returns
-
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
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
properties? (sourcedproperties) – a dictionary of properties corresponding to 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)¶ - Parameters
brids (list(integer)) – list of buildrequest id to claim
claimed_at (datetime) – date and time when the buildrequest is claimed
- Returns
(boolean) whether claim succeeded or not
Claim 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)¶ - 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
Complete a list of buildrequest with the
results
status
-
Endpoints¶
-
path:
/builders/{builderid_or_buildername}/buildrequests
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
This path selects all buildrequests for a given builder (can return lots of data!)
GET
returns
-
path:
/buildrequests
GET
returns
-
path:
/buildrequests/{buildrequestid}
- Path Keys
buildrequestid (number) – the id of the buildrequest
GET
returns
-
POST with method:
/buildrequests/{buildrequestid} (method=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 a 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
entitysubmitted_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 a 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.
-
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 resource 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
ofchange
-
path:
/changes
This path selects all changes.
On a reasonably 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
ofchange
-
path:
/changes/{changeid}
- Path Keys
changeid (number) – the id of a change
this path selects one change by id
GET
returns
collection
ofchange
-
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
ofchange
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
orFalse
, 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
-
path:
/changesources/{changesourceid}
- Path Keys
changesourceid (number) – the id of a changesource
This path selects one changesource given its id.
GET
returns
-
path:
/masters/{masterid}/changesources
- Path Keys
masterid (number) – the id of the master
This path selects all changesources for a given master
GET
returns
-
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
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_or_buildername}/forceschedulers
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
This path selects all force-schedulers for a given builder
GET
returns
-
path:
/forceschedulers
This path selects all forceschedulers.
GET
returns
-
path:
/forceschedulers/{schedulername}
- Path Keys
schedulername (identifier) – the name of a scheduler
This path selects all changesource.
GET
returns
-
POST with method:
/forceschedulers/{schedulername} (method=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_or_buildername}/builds/{build_number}/steps/{step_name}/logs
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
oflog
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_name}/logs/{log_slug}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
oflog
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}/logs
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
oflog
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}/logs/{log_slug}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
oflog
-
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
oflog
-
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
oflog
-
path:
/logs/{logid}
- Path Keys
logid (number) – the id of the log
This path selects one log
GET
returns
collection
oflog
-
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
oflog
-
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
oflog
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
d
– Deleted, logchunks for this log have been deleted by the Janitor
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_or_buildername}/builds/{build_number}/steps/{step_name}/logs/{log_slug}/contents
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}/logs/{log_slug}/contents
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
-
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
-
path:
/logs/{logid}/contents
- Path Keys
logid (number) – the id of the log
GET
returns
-
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
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_or_buildername}/masters
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
This path selects all masters supporting a given builder
GET
returns
collection
ofmaster
-
path:
/builders/{builderid_or_buildername}/{masterid}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
masterid (number) – the id of the master
This path selects a master by id filtered by given builderid
GET
returns
collection
ofmaster
-
path:
/masters
This path selects all masters
GET
returns
collection
ofmaster
-
path:
/masters/{masterid}
- Path Keys
masterid (number) – the id of the master
This path selects one master given its id
GET
returns
collection
ofmaster
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
orFalse
, 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
-
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
-
path:
/schedulers
This path selects all schedulers
GET
returns
-
path:
/schedulers/{schedulerid}
- Path Keys
schedulerid (number) – the id of the scheduler
This path selects one scheduler by id
GET
returns
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
-
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
sourcestamp¶
-
resource type:
sourcestamp
- Attributes
ssid (integer) –
the ID of this sourcestamp
Note
For legacy reasons, the abbreviated name
ssid
is used instead of canonicalsourcestampid
. 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.
spec¶
-
resource type:
spec
- Attributes
path (string) –
plural (string) –
type (string) –
type_spec (object) –
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_or_buildername}/builds/{build_number}/steps
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
ofstep
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_name}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
ofstep
-
path:
/builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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
ofstep
-
path:
/builds/{buildid}/steps
- Path Keys
buildid (number) – the id of the build
This path selects all steps of a build
GET
returns
collection
ofstep
-
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
ofstep
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
paused (bool) – the worker is paused if it is connected but doesn’t accept new builds.
graceful (bool) – the worker is graceful if it doesn’t accept new builds, and will shutdown when builds are finished.
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_or_buildername}/workers
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
This path selects all workers configured for a given builder
GET
returns
collection
ofworker
-
path:
/builders/{builderid_or_buildername}/workers/{name}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
name (identifier) – the name of the worker
This path selects a worker by name filtered by given builderid
GET
returns
collection
ofworker
-
path:
/builders/{builderid_or_buildername}/workers/{workerid}
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name of the builder
workerid (number) – the id of the worker
This path selects a worker by id filtered by given builderid
GET
returns
collection
ofworker
-
POST with method:
/builders/{builderid_or_buildername}/workers/{workerid} (method=stop)
- Body keys
method (string) – must be
stop
reason (string) – The reason why the worker was stopped
-
POST with method:
/builders/{builderid_or_buildername}/workers/{workerid} (method=kill)
- Body keys
method (string) – must be
kill
reason (string) – The reason why the worker was stopped
-
POST with method:
/builders/{builderid_or_buildername}/workers/{workerid} (method=pause)
- Body keys
method (string) – must be
pause
reason (string) – The reason why the worker was paused
-
POST with method:
/builders/{builderid_or_buildername}/workers/{workerid} (method=unpause)
- Body keys
method (string) – must be
unpause
reason (string) – The reason why the worker was un-paused
-
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
ofworker
-
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
ofworker
-
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
ofworker
-
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
ofworker
-
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
ofworker
-
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
ofworker
-
path:
/workers
this path selects all workers
GET
returns
collection
ofworker
-
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
ofworker
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_or_buildername}/builds/{build_number}/steps/{step_name}/logs/{log_slug}/raw
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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_or_buildername}/builds/{build_number}/steps/{step_number}/logs/{log_slug}/raw
- Path Keys
| identifier builderid_or_buildername (number) – the ID or name 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_or_buildername}:
uriParameters:
builderid_or_buildername:
type: number | identifier
description: the ID or name 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}
/actions/stop:
post:
description: |
gracefully shutdown one worker.
body:
application/json:
properties:
reason:
type: string
required: false
description: The reason why the worker was stopped
/actions/kill:
post:
description: |
forcefully shutdown one worker.
body:
application/json:
properties:
reason:
type: string
required: false
description: The reason why the worker was stopped
/actions/pause:
post:
description: |
Pause one worker. The worker will stop taking new build.
body:
application/json:
properties:
reason:
type: string
required: false
description: The reason why the worker was paused
/actions/unpause:
post:
description: |
Unpause one worker. The worker will re-start taking builds.
body:
application/json:
properties:
reason:
type: string
required: false
description: The reason why the worker was un-paused
/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 reasonably 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: