Today, we are announcing v2 of our API, which opens nine new stable endpoints that allow for control of pipelines and workflows. The v2 API has been in preview release for several months, and we will continue to add new endpoints over time, including some that are available today as an unstable preview for a while longer.

In this post, I’ll outline the first endpoints in the v2 API that are now stable for your production use.

Pipelines are now first-class in the API

In March 2019, we announced a simple name change of “build processing” to “pipelines” and told you it would be a while before you had to think about pipelines again. Since then many of you have seen pipelines appear in the preview releases of the v2 API and in our new UI preview. With the v2 API we expand pipelines to give you programmatic access to triggering and retrieving them.

Pipelines encapsulate what you run on CircleCI. When you trigger a pipeline with a commit to your git repository or an API call against a project, that pipeline represents the beginning of your request to do work inside of CircleCI and persists a stable pipeline ID along with information about the cause of the trigger, the actor to whom we will attribute the run of the pipeline, and the configuration used to run the workflows in the pipeline.

A pipeline 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).

If you added your project after Sept 2018 you have been using pipelines and may not have even realized it.

The “project_slug”

The CircleCI v2 API uses an identifier for your projects that corresponds to their upstream repository. For instance, if you want to pull information from CircleCI about the GitHub repository https://github.com/CircleCI-Public/circleci-cli, you can refer to that in the CircleCI API as gh/CircleCI-Public/circleci-cli, which is a “triplet” of the project type, the name of your “organization”, and the name of the repository. For the project type you can use github or bitbucket as well as the shorter forms gh or bb, which are now supported in API v2). The organization is your username or organization name in your version control system.

With API v2 we are introducing a string representation of the triplet called the project_slug, which takes the form: <project_type>/<org_name>/<repo_name>. The project_slug is included in the payload when pulling information about a project as well as when looking up a pipeline or workflow by ID. The project_slug can then be used to get information about the project. It’s possible in the future we could change the shape of a project_slug, but in all cases it would be usable as a human-readable identifier for a given project.

Pipeline parameters

The v2 API now allows you to add parameters to your pipeline triggers.

To trigger a pipeline with parameters you pass the parameters key in the JSON packet in your POST body. For the above config this might look something like:

curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
  "parameters": {
    "workingdir": "./myspecialdir",
    "image-tag": "4.8.2"
  }
}' https://circleci.com/api/v2/project/:project_slug/pipeline

Unlike parameters in the v1.1 job triggering endpoint, which were injected directly into the running job environment, pipeline parameters resolve during configuration processing, making them available to most parts of your configuration.

Pipeline parameters are declared using a parameters stanza in the top level keys of your .circleci/config.yml file. You then reference the value of the parameter in the scope pipeline.parameters.

The example belows shows a config with two pipeline parameters, image-tag and workingdir both used on the subsequent config stanzas:

version: 2.1
parameters:
  image-tag:
    type: enum
    default: "latest"
    enum: ["latest","bleeding","stable201911"]
    # NOTE use of enum allows only the options you want
    # You could, instead, choose to make it an arbitrary string
  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 >>"

Keep in mind that if you declare a pipeline parameter, anyone with a triggering credential (for instance, an API token tied to a user who has triggering rights by virtue of having commit rights on the upstream repo) will be able to effectively inject that value into your configuration. In the example above if you did not want to allow injection of a docker tag you would not want to use this technique.

Conditional workflows using pipeline parameters

We added a new when clause (we also support the inverse clause unless) under a workflow declaration with a boolean value to decide whether or not to run that workflow.

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.

Below is an example configuration using two different pipeline parameters, one used to drive whether a particular workflow will run and another to determine if a particular step will run.

version: 2.1

parameters:
  run_integration_tests:
    type: boolean
    default: false
  deploy:
    type: boolean
    default: false

workflows:
  version: 2
  integration_tests:
    when: << pipeline.parameters.run_integration_tests >>
    jobs:
      - mytestjob

jobs:
  mytestjob:
    steps:
      - checkout
      - when:
          condition: << pipeline.parameters.deploy >>
          steps:
            - run: echo "deploying"

Nine new endpoints

The stars in today’s announcement of v2 is the stability and general availability of the first set of endpoints in the CircleCI API v2 (pipelines and workflows).

The following pipeline endpoints let you, respectively,

  • Trigger a pipeline on a project branch and receive its ID for later use
  • Retrieve the latest pipelines on a given project
  • Filter down the recent pipelines run by the requestor
POST /project/{project-slug}/pipeline
GET  /project/{project-slug}/pipeline
GET  /project/{project-slug}/pipeline/mine

You can also

  • Retrieve an individual pipeline by its ID
  • Retrieve a pipeline’s workflows
  • Retrieve both the source and processed configuration that was used to run the pipeline
GET  /pipeline/{pipeline-id}
GET  /pipeline/{pipeline-id}/workflow
GET  /pipeline/{pipeline-id}/config

The other three new endpoints allow you to

  • Retrieve an individual workflow
  • Retrieve an individual workflow’s jobs
  • There’s also an endpoint to cancel a workflow
GET  /workflow/{id}
GET  /workflow/{id}/job
POST /workflow/{id}/cancel

CircleCI API v2 supports OpenAPI

With API v2 we now have full support for OpenAPI 3. You can download a live spec that reflects the current production API here:

Learn more