NAV Navbar
shell ruby python javascript

Setup

You need an HTTP library installed to use the Layer API. See code pane for details.

#in bash terminal
gem install bundler
bundle install faraday

#at top of file
require 'faraday'
require 'json'
#in bash terminal
pip install requests

#at top of file
import requests
#in bash terminal (ubuntu)
sudo apt-get update
sudo apt-get install -y curl ca-certificates

#other distributions - google "how to install curl"
//for javascript, we use use fetch()
//for nodejs, https://www.npmjs.com/package/node-fetch
//i.e., npm install --save node-fetch

CI Jobs

Layerfile runner objects

Each time you look at the dashboard for a run, you're looking at a collection of layerfile runners. Each layerfile runner is created by a specific Layerfile, or by a Layerfile being retried.

CI jobs are a collection of Layerfile runners!

CI job example schema

{
    "repository_name": "layerci-example",
    "id": 1,
    "status": "SEE_RUNNERS",
    "status_change_time": "2000-01-01 01:23:45.123456 +0000 UTC",
    "calculated_status": "SUCCEEDED",
    "commit_sha": "9abc2ac68d52afe1a5a3fbc724d031af5a397204",
    "branch": "master",
    "merge_branch": "master",
    "run_start_reason": "Manual run created by API",
    "run_start_reason_url": ""
}

status vs. calculated_status

CI jobs themselves maintain an internal status which is either:

CI jobs also contain a status which is the calculated status of the whole job, looking at the runners. The calculated status is usually what you'll use to determine the status of an entire run.

The calculated_status of a CI job is one of the following:

Get most recent CI job for a repository matching the given filters

It's often useful to get the most recent CI job given specific filters. This API endpoint allows for that.

Possible filters are:

You can include multiple filters to require multiple conditions to be true.

require 'faraday'
require 'json'

# get the most recent failing jobs
res = Faraday.get 'https://layerci.com/api/v1/run/repo_name/latest?calculated_status=FAILURE&layertoken=(your api key)'

res = JSON.parse(res.body)
import requests

# get the most recent failing job
my_token="(your API key)"
res = requests.get(
    f'https://layerci.com/api/v1/jobs/github/repo_owner/repo_name/latest?done=true&layertoken={my_token}', 
).json()
# get the most recent failing job
my_token="(your API key)"
curl "https://layerci.com/api/v1/run/repo_name/latest?calculated_status=FAILURE&layertoken=${my_token}"
let apiKey="(your API key)"
fetch(
    'https://layerci.com/api/v1/run/repo_name/latest?calculated_status=FAILURE&layertoken='+apiKey,
).then(res => res.json()).then(json => console.log(json))

Output:

{
    "status": "ok",
    "job": {
        "repository_name": "layerci-example",
        "id": 3,
        "status": "SEE_RUNNERS",
        "status_change_time": "2000-01-01 01:23:45.123456 +0000 UTC",
        "calculated_status": "SUCCEEDED",
        "commit_sha": "9abc2ac68d52afe1a5a3fbc724d031af5a397204",
        "branch": "master",
        "merge_branch": "master",
        "run_start_reason": "Manual run created by API",
        "run_start_reason_url": ""
    }
}

"status" can be one of "ok" or "error". If the latter exists, an "error" value will be included with an explanation.

Create a CI job for a given repository

Sometimes it's useful to manually start LayerCI runs (for, e.g., deploying) This endpoint lets you do that.

The input to the POST is optional, but can contain:

require 'faraday'
require 'json'

res = Faraday.post(
    'https://layerci.com/api/v1/run/repo_name?layertoken=(your api key)',
    {
        branch: 'master',
        ref: '9abc2ac68d52afe1a5a3fbc724d031af5a397204',
        accept_buttons: 'true',
        skip_no_further_than: 'run-and-deploy',
    }.to_json
)

res = JSON.parse(res.body)
import requests

my_token="(your API key)"
res = requests.post(
    f'https://layerci.com/api/v1/run/repo_name?layertoken={my_token}',
    json={
        'branch': 'master',
        'ref': '9abc2ac68d52afe1a5a3fbc724d031af5a397204',
        'accept_buttons': 'true',
        'skip_no_further_than': 'run-and-deploy',
    },
).json()
my_token="(your API key)"
curl -X POST \
    -H 'Content-Type: application/json' \
    -d '{"branch": "master", \
         "ref": "9abc2ac68d52afe1a5a3fbc724d031af5a397204", \
         "accept_buttons": "true", \
         "skip_no_further_than": "run-and-deploy"
        }' \
    "https://layerci.com/api/v1/run/repo_name?layertoken=${my_token}"
let apiKey="(your API key)"
fetch(
    'https://layerci.com/api/v1/run/repo_name?layertoken='+apiKey,
    {
        method: "POST",
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            'branch': 'master',
            'ref': '9abc2ac68d52afe1a5a3fbc724d031af5a397204',
            'accept_buttons': 'true',
            'skip_no_further_than': 'run-and-deploy',
        }),
    }
).then(res => res.json()).then(json => console.log(json))

Output:

{
    "status": "ok",
    "job": {
        "repository_name": "layerci-example",
        "id": 1,
        "status": "NEW",
        "status_change_time": "2020-05-05 05:11:44.17955 +0000 UTC",
        "calculated_status": "NEW",
        "commit_sha": "9abc2ac68d52afe1a5a3fbc724d031af5a397204",
        "branch": "master",
        "merge_branch": "master",
        "run_start_reason": "Manual run created by API",
        "run_start_reason_url": ""
    },
    "url": "http://layerci.com/jobs/github/distributed-containers-inc/layerci-example/1"
}

"status" can be one of "ok" or "error". If the latter exists, an "error" value will be included with an explanation.