User:Catlee/BuildAPI

From MozillaWiki
Jump to navigation Jump to search

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.

Retrieved from "https://wiki.allizom.org/index.php?title=User:Catlee/BuildAPI&oldid=272532"