3.3.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.3.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 was json, not api/v1. |
3.3.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.3.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=cccchttp://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=10http://build.example.org/api/v2/buildrequest?order=builderid&offset=20&limit=10
3.3.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.3.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.3.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!)
GETreturnscollectionofbuild
-
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
GETreturnscollectionofbuild
-
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)
- method (string) – must be
-
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
GETreturnscollectionofbuild
-
path:
/builds
GETreturnscollectionofbuild
-
path:
/builds/{buildid} Path Keys: buildid (number) – the id of the build
This path selects a build by id
GETreturnscollectionofbuild
-
POST with method:
/builds/{buildid} (method=stop) Body keys: - method (string) – must be
stop - reason (string) – The reason why the build was stopped
- method (string) – must be
-
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
GETreturnscollectionofbuilder
-
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
GETreturnscollectionofbuilder
-
path:
/masters/{masterid}/builders Path Keys: masterid (number) – the id of the master
This path selects all builders of a given master
GETreturnscollectionofbuilder
-
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
GETreturnscollectionofbuilder
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_atis None
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, _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_atis None
Complete a list of buildrequest with the
resultsstatus
-
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!)
GETreturnscollectionofbuildrequest
-
path:
/buildrequests
GETreturnscollectionofbuildrequest
-
path:
/buildrequests/{buildrequestid} Path Keys: buildrequestid (number) – the id of the buildrequest
GETreturnscollectionofbuildrequest
-
POST with method:
/buildrequests/{buildrequestid} (method=cancel) Body keys: - method (string) – must be
cancel - reason (string) – The reason why the buildrequest was cancelled
- method (string) – must be
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
sourcestampentity - 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 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.
-
Endpoints¶
-
path:
/buildsets
this path selects all buildsets
GETreturnscollectionofbuildset
-
path:
/buildsets/{bsid} Path Keys: bsid (identifier) – the id of the buildset
this path selects a buildset by id
GETreturnscollectionofbuildset
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
GETreturnscollectionofchange
-
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>
GETreturnscollectionofchange
-
path:
/changes/{changeid} Path Keys: changeid (number) – the id of a change
this path selects one change by id
GETreturnscollectionofchange
-
path:
/sourcestamps/{ssid}/changes Path Keys: ssid (number) – the id of the sourcestamp
This path selects all changes associated to one sourcestamp
GETreturnscollectionofchange
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: TrueorFalse, via DeferredTry to claim the given scheduler for the given master and return
Trueif the scheduler is to be activated on that master.
-
Endpoints¶
-
path:
/changesources
This path selects all changesource.
GETreturnscollectionofchangesource
-
path:
/changesources/{changesourceid} Path Keys: changesourceid (number) – the id of a changesource
This path selects one changesource given its id.
GETreturnscollectionofchangesource
-
path:
/masters/{masterid}/changesources Path Keys: masterid (number) – the id of the master
This path selects all changesources for a given master
GETreturnscollectionofchangesource
-
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
GETreturnscollectionofchangesource
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
GETreturnscollectionofforcescheduler
-
path:
/forceschedulers
This path selects all forceschedulers.
GETreturnscollectionofforcescheduler
-
path:
/forceschedulers/{schedulername} Path Keys: schedulername (identifier) – the name of a scheduler
This path selects all changesource.
GETreturnscollectionofforcescheduler
-
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
- method (string) – must be
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
logchunkfor 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.
GETreturnscollectionoflog
-
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
GETreturnscollectionoflog
-
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
GETreturnscollectionoflog
-
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
GETreturnscollectionoflog
-
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
GETreturnscollectionoflog
-
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
GETreturnscollectionoflog
-
path:
/logs/{logid} Path Keys: logid (number) – the id of the log
This path selects one log
GETreturnscollectionoflog
-
path:
/steps/{stepid}/logs Path Keys: stepid (number) – the id of the step
This path selects all logs for the given step.
GETreturnscollectionoflog
-
path:
/steps/{stepid}/logs/{log_slug} Path Keys: - stepid (number) – the id of the step
- log_slug (identifier) – the slug name of the log
GETreturnscollectionoflog
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 texts– stdio, like text but with each line tagged with a streamh– HTML, represented as plain textd– 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
GETreturnscollectionoflogchunk
-
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
GETreturnscollectionoflogchunk
-
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
GETreturnscollectionoflogchunk
-
path:
/logs/{logid}/contents Path Keys: logid (number) – the id of the log
GETreturnscollectionoflogchunk
-
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
GETreturnscollectionoflogchunk
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.
- name (unicode) – the name of this master (generally
-
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
GETreturnscollectionofmaster
-
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
GETreturnscollectionofmaster
-
path:
/masters
This path selects all masters
GETreturnscollectionofmaster
-
path:
/masters/{masterid} Path Keys: masterid (number) – the id of the master
This path selects one master given its id
GETreturnscollectionofmaster
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: TrueorFalse, via DeferredTry to claim the given scheduler for the given master and return
Trueif 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
GETreturnscollectionofscheduler
-
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
GETreturnscollectionofscheduler
-
path:
/schedulers
This path selects all schedulers
GETreturnscollectionofscheduler
-
path:
/schedulers/{schedulerid} Path Keys: schedulerid (number) – the id of the scheduler
This path selects one scheduler by id
GETreturnscollectionofscheduler
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
GETreturnscollectionofsourcedproperties
-
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.
GETreturnscollectionofsourcedproperties
sourcestamp¶
-
resource type:
sourcestamp Attributes: - ssid (integer) –
the ID of this sourcestamp
Note
For legacy reasons, the abbreviated name
ssidis 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
- ssid (integer) –
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!)
GETreturnscollectionofsourcestamp
-
path:
/sourcestamps/{ssid} Path Keys: ssid (number) – the id of the sourcestamp
This path selects one sourcestamp by id
GETreturnscollectionofsourcestamp
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.
GETreturnscollectionofstep
-
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.
GETreturnscollectionofstep
-
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
GETreturnscollectionofstep
-
path:
/builds/{buildid}/steps Path Keys: buildid (number) – the id of the build
This path selects all steps of a build
GETreturnscollectionofstep
-
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
GETreturnscollectionofstep
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
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
-
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
- method (string) – must be
-
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
- method (string) – must be
-
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
- method (string) – must be
-
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
- method (string) – must be
-
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
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
-
path:
/masters/{masterid}/workers Path Keys: masterid (number) – the id of the master
This path selects all workers for a given master
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
-
path:
/workers
this path selects all workers
GETreturnscollectionofworker
-
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
GETreturnscollectionofworker
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 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:
