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"}

Back