CircleCIは、そのAPIのバージョン2リリースでインサイトエンドポイントの安定性が向上した。インサイトエンドポイントを使用すると、ジョブとワークフローのステータスを追跡し、ジョブの期間を監視し、リソース消費を最適化する可能性を調査できる。
この発表により、4つの新しいエンドポイントがAPIに追加された。ジョブレベルまたはワークフローレベルで集計データを表示できるようになった。これには、成功した実行数と失敗した実行数、スループット（1日あたりの平均実行数）、平均回復時間、使用された合計クレジットなどのデータが含まれる。期間統計の場合、データは、最大、最小、平均、中央値、p95、標準偏差などのいくつかの統計が返される。特定のワークフローの集計データを取得するには、次のエンドポイントを使用できる。
GET https://circleci.com/api/v2/insights/{project-slug}/workflows
最大90日前までさかのぼって直近の実行データを取得することも可能である。たとえば、特定のワークフローのジョブ実行データを取得するには、次のAPIを呼び出すことができる。
GET https://circleci.com/api/v2/insights/{project-slug}/workflows/{workflow-name}/jobs/{job-name}
応答には、ジョブの開始時刻、停止時刻、およびそのステータスが含まれる。また、ジョブの実行に使用されたクレジットの数も提供される。
新しいAPIは、project_slugと呼ばれるアップストリームリポジトリに対応するプロジェクトの識別子を使用する。project_slugの形式は<project_type>/<org_name>/<repo_name>である。たとえば、GitHubリポジトリhttps://github.com/CircleCI-Public/circleci-cliの場合、project_slugはgh/CircleCI-Public/circleci-cliになる。project_typeについては、GitHubにはgithubまたはghを使用できる。BitBucketリポジトリには、bitbucketまたはbbを使用できる。
バージョン2のAPIのリリースにより、パイプラインはAPIのファーストクラスの扱いになった。2019年、CircleCIは「ビルド処理」の概念を「パイプライン」に名前変更した。CircleCIのプロダクトマネージャーであるNathan Dintenfass氏がパイプラインについて述べている。
それは、CircleCIに要求された作業単位です。それぞれは、特定のプロジェクト、あるいは特定のブランチ（デフォルトのブランチがデフォルト値として適用されます）で、特定の構成を持つ特定のアクター（または、過去のGitHub統合のように、アップストリームで構成を取得する暗黙の方法）によってトリガーされます。
v2 APIで、パイプライントリガーにパラメーターを追加できるようになった。これは、POST本文のJSONパケットでパラメーターキーを渡すことによって実現される。バージョン2では、パイプラインパラメーターは構成処理中に解決される。これにより、構成のほとんどの部分でそれらを使用できるようになる。これは、パラメーターがジョブ環境に直接注入されるv1.1 APIとは異なる。
パイプラインパラメーターは、config.ymlファイルのparametersオブジェクトを使用して宣言される。それらは次に、pipeline.parametersを使用して参照される。たとえば、以下の構成では、image-tagとworkingdirの2つのパイプラインパラメーターが定義されている。
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 >>"
いつ実行するか、何を実行しないかを定義する項目も追加されている。これは、特定のワークフローを実行するかどうかを決定するのに役立つ。Dintenfass氏によると、「この構成の最も一般的な使用方法は、パイプラインパラメーターを値として使用し、APIトリガーがそのパラメーターを渡して、実行するワークフローを決定できるようにすること」である。
CircleCI API v2はOpenAPI 3を完全にサポートしている。JSONとYAMLの両方で利用可能な本番APIのライブ仕様がある。APIの将来のバージョンのプレビューリリースドキュメントもレビューできる。