CircleCI has improved the stability of their insights endpoints in the version 2 release of their API. The insights endpoints allow for tracking the status of jobs and workflows, monitoring the duration of jobs, and investigating opportunities for optimizing resource consumption.
With this announcement, four new endpoints have been added to the API. It is now possible to view aggregate data at the job or workflow level. This includes data such as the number of successful and failed runs, the throughput (average number of runs/day), the mean time to recover, and the total credits used. For the duration statistics the data is returned with a number of statistics including max, min, mean, median, p95, and standard deviation. To retrieve aggregated data for a particular workflow, the following endpoint can be used:
GET https://circleci.com/api/v2/insights/{project-slug}/workflows
It is also possible to retrieve data for the most recent runs going back at most 90 days. For example, to retrieve job execution data for a particular workflow, the following API can be called:
GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}
The response includes when the job started, stopped, and its status. It also provides the number of credits used in running the job.
The new API uses an identifier for projects that corresponds to their upstream repository known as the project_slug. The project_slug is of the form <project_type>/<org_name>/<repo_name>. For example, for a GitHub repository https://github.com/CircleCI-Public/circleci-cli, the project_slug would be gh/CircleCI-Public/circleci-cli. For project_type it is possible to use github or gh for GitHub, or bitbucket or bb or BitBucket repositories.
The release of the version 2 API saw pipelines becoming a first-class citizen in the API. In 2019, CircleCI renamed the concept of "build processing" to "pipelines". According to Nathan Dintenfass, product manager with CircleCI, a pipeline is
is a unit of work requested of CircleCI. Each is triggered on a given project, on a given branch (your default branch applies as default value), by a particular actor with a particular configuration (or an implied way to retrieve configuration upstream, as with our historic GitHub integration).
The v2 API now allows for the addition of parameters to pipeline triggers. This is accomplished by passing the parameters key in the JSON packet in the POST body. In version 2 pipeline parameters are resolved during configuration processing. This allows them to be available to most parts of the configuration. This differs from the v1.1 API in which parameters were injected directly into the job environment.
Pipeline parameters are declared using the parameters object in the config.yml file. They are then referenced using pipeline.parameters. For example, the config below defines two pipeline parameters: image-tag and workingdir:
version: 2.1
parameters:
image-tag:
type: enum
default: "latest"
enum: ["latest","bleeding","stable201911"]
workingdir:
type: string
default: "main-app"
jobs:
build:
docker:
- image: circleci/node:<< pipeline.parameters.image-tag >>
environment:
IMAGETAG: << pipeline.parameters.image-tag >>
working_directory: /Code/<< pipeline.parameters.workingdir >>
steps:
- run: echo "Image tag used was ${IMAGETAG}"
- run: echo "$(pwd) == << pipeline.parameters.workingdir >>"
There are also additional clauses to help decide whether or not to run a particular workflow. According to Dintenfass, "The most common use of this construct is to use a pipeline parameter as the value, allowing an API trigger to pass that parameter to determine which workflows to run."
The CircleCI API v2 has full support for OpenAPI 3. There are live specs for the production API available for both JSON and YAML. The preview release documentation for future versions of the API is also available for review.
