REST Interface

List of request methods, urls, and parameters

PUT and DELETE can also be achieved by POSTing to the URL with a POST field "_method" set to PUT or DELETE.

PUT, POST, and DELETE methods will return a job id that can be queried with the 'job_status' method.

GET /builds/branches -> list of branches

GET /builds/{branch} -> list of recent builds, including completed, running and pending

GET /builds/{branch}/build/{buildid} -> information about a particular build

GET /builds/{branch}/request/{requestid} -> information about a particular build request

GET /builds/{branch}/rev/{revision} -> list of builds for this revision

GET /builds/{branch}/builders -> list of valid builder names

GET /builds/{branch}/builders/{buildername} -> list of recent builds, including completed, running, and pending for this builder name

GET /builds/jobs/{job_id} -> status on job request (e.g. cancel build, etc.)

PUT /builds/{branch}/request/{requestid} -> update this build

• priority (required, sets the build request's priority)

DELETE /builds/{branch}/build/{buildid} -> cancel this build

DELETE /builds/{branch}/request/{requestid} -> cancel this buildrequest

• onlyifrunning (optional, set to only cancel builds if they're running)
• onlyifpending (optional, set to only cancel builds if they're pending)

DELETE /builds/{branch}/rev/{revision} -> cancel pending/running builds for this revision

• onlyifrunning (optional, set to only cancel builds if they're running)
• onlyifpending (optional, set to only cancel builds if they're pending)
• killmerged (optional, set to cancel builds that are merged with other revisions)

POST /builds/{branch}/rev/{revision} -> create a new build with this revision

• properties (optional, extra properties for this build)

POST /builds/{branch}/builders/{buildername} -> create a new build on this builder

• revision (optional, which revision to build)
• properties (optional, extra properties for this build)

POST /builds/{branch}/build -> rebuilds an old build on this branch

• buildid (which build to rebuild)
• properties (optional, extra properties for this build)

POST /builds/{branch}/request -> rebuilds an old build on this branch

• requestid (which request to rebuild)
• properties (optional, extra properties for this build)

Object definitions

Builds:

• buildid
• buildrequests
• buildnumber
• buildername
• branch
• revision
• starttime
• endtime
• status

Build Requests:

• buildrequestid
• buildername
• branch
• revision
• submittime

Implementation Notes

(source at http://hg.mozilla.org/users/catlee_mozilla.com/buildapi/file/493320c66935/RESTAPI_NOTES.txt)

Routing

Or, how do URLs get turned into method calls?

Look in buildapi/config/routing.py. All the /builds/ urls are to support the REST API.

URLs get matched to an appropriate route based on these rules, and then methods in buildapi/controllers/builds.py are called.

GETting data

Most GET queries do a few simple operations:

1) validate parameters

2) make db calls with methods in buildapi/model/builds

3) return results

Results are formatted according to the 'format' query parameter ("?format=html" or "?format=json"). If 'format' is not set, and the 'Accept' header of the request is set to 'application/json', the format will be set to json. Otherwise the format will be html. These rules are implemented in buildapi.lib.base.BaseController._get_method_args.

Job Requests

PUT, POST, and DELETE requests (which can be faked by setting a '_method_' field to 'PUT' or 'DELETE' in a regular POST request if your client doesn't support PUT/DELETE easiliy...a nice feature of Routes!) represent requests to change buildbot state. These are called "Job Requests".

Job requests follow a simple flow:

1) log request in jobrequests table of buildapi database. Return jobrequest id to client. The client can query the status of this job via the /builds/job_status/{job_id} method.

2) send message to message broker on the 'requests' routing key with details of job request.

3) an external agent (such as buildapi/scripts/buildapi-agent.py) receives the message, acts on it, and then sends a message on the 'finished' routing key to indicate the job was completed. TODO: agent should have a way of attaching failure information

4) a thread in the web app is waiting for messages on the 'finished' routing key. It will update the jobrequests table when jobs are completed.