API Docs
ClusterRunner is built around a REST API. We use HMAC along with a configurable application secret for securing communication between service components. JSON is returned in all responses, and is used in POST requests.
Authentication
You authenticate a request by providing a header key-value pair for ClusterRunner-Message-Authentication-Digest. The value of the HMAC is generated using the body of the request along with a secret is located in clusterrunner.conf.
Responses
ClusterRunner uses HTTP response codes to indicate success or failure as well as a JSON body for additional information. The JSON response will include request specific information, along with a STATUS field that will either be SUCCESS or FAILURE.
Versioning
We version all of our APIs and make a major version bump whenever we make incompatible changes. Currently we are on v1.
Builds
The build endpoint is located on the ClusterRunner master.
List all builds
Request
GET /build
Response
{ "builds": [ { ... } ], "child_routes": { ... } }
Get information about a single build
Request
GET /build/1/
Response
"build": { "details": "534 of 637 subjobs are complete (83.8%).", "num_subjobs": 637, "failed_atoms": null, "artifacts": null, "status": "BUILDING", "result": null, "num_atoms": 2684, "id": 1, "error_message": null }
Creating a new build
To run a new build, you create a new build object. The response will contain the id of the new build object, which you can can later poll for the status of your build. A build can have a status of either BUILDING, SUCCESS, or FAILURE. While a request is building, certain fields on the object may remain null. On completion, all the fields will contain their actual values.
Request
POST /build
Creating a new build object requires properly authenticating your request with the correct HMAC, (see Authentication), and providing a JSON body that defines your build. Here are the available arguments for creating a build:
Name | Description |
---|---|
type |
Required The project type of the new build. Should be set to "git". |
job_name |
Required The name of the job to run on the new build. |
url |
Required url to the git repo |
remote |
Optional The git remote name to fetch from |
branch |
Optional The git remote branch name to fetch from |
hash |
Optional The git hash on the remote to reset hard to |
remote_files |
Optional JSON dictionary that maps downloadable URI's to output file names. If present, each URI will be downloaded into the build workspace under the specified name. |
Response
202 ACCEPTED
{"build_id": 1, "STATUS": "SUCCESS"}