Build APIリファレンス

Build APIを使うと、アプリや設定、プラットフォームのリソースにプログラムからアクセスできます。Build.ioをCI/CDパイプラインに組み込んだり、デプロイを自動化したり、独自のツールを作ったりするときに使います。

インタラクティブドキュメント

リクエストとレスポンスの詳しいスキーマは、Swaggerドキュメントで確認できます。エンドポイントをその場で呼び出して試すこともできます：

https://app.build.io/api-docs/index.html

HTTPのBasic認証を求められたら、ユーザー名にbuild、パスワードにbestを入力します。

ベースURL

APIリクエストはすべて次のURLに送信します：

https://app.build.io/api/v1

認証

APIは複数の認証方式に対応しています。ほとんどの場合、Bearerトークンを使う方法が最も簡単です。

トークンはAuthorizationヘッダーに指定します：

Authorization: Bearer your-token-here

ユーザーに代わって操作するアプリケーション向けに、OAuth 2.0にも対応しています。認可エンドポイントとトークンエンドポイントは次のとおりです：

Authorization: https://app.build.io/oauth/authorize

Token: https://app.build.io/oauth/token

利用できるOAuthスコープはreadとwriteです。

リクエストとレスポンスの形式

APIはJSONでリクエストを受け付け、JSONでレスポンスを返します。リクエストボディを送る場合は、Content-Typeヘッダーを指定します：

Content-Type: application/json

単一のリソースを返すエンドポイントは、ほとんどがJSONオブジェクトを返します。複数のリソースを返すエンドポイントは、JSON配列を返します。

エラー

リクエストが失敗すると、APIはエラーレスポンスを返します。レスポンスには、プログラムで判別するためのコードと、人が読むためのメッセージが含まれます：

{
  "code": "not_found",
  "message": "The requested resource was not found"
}

リソースの概要

APIは次のリソースで構成されています：

アプリ

アプリはBuild.ioの中心となるリソースで、1つのアプリが1つのデプロイ済みアプリケーションに対応します。

GET /apps — アクセスできるアプリを一覧表示します。クエリパラメータteam_idでチームを指定して絞り込めます。

GET /apps/{app_id_or_name} — 特定のアプリの詳細（フォーメーション、ビルドパック、リージョン、現在のデプロイ状態など）を取得します。

POST /apps — 新しいアプリを作成します。nameは必須、team_idとregionは省略できます。

ビルド

アプリの新しいビルドを開始します。

POST /apps/{app_id_or_name}/builds — ビルドを開始します。ブランチ、コミット（commitish）、説明を任意で指定できます。

Config Var

アプリのConfig Var（アプリに環境変数として渡される設定値）を管理します。

GET /apps/{app_id_or_name}/config-vars — すべてのConfig Varをキーと値のペアで一覧表示します。

PATCH /apps/{app_id_or_name}/config-vars — Config Varを設定または更新します。設定するキーと値をJSONオブジェクトで送信します。

DELETE /apps/{app_id_or_name}/config-vars/{key} — 特定のConfig Varを削除します。

ドメイン

カスタムドメインとSSL証明書を管理します。

GET /apps/{app_id_or_name}/domains — アプリのすべてのドメイン（プラットフォームドメインとカスタムドメイン）を一覧表示します。

POST /apps/{app_id_or_name}/domains — カスタムドメインを追加します。hostnameは必須、certは省略できます。

GET /apps/{app_id_or_name}/domains/{domain_id} — 特定のドメインの詳細（SSLの状態など）を取得します。

PATCH /apps/{app_id_or_name}/domains/{domain_id} — ドメインのSSL証明書を更新します。

DELETE /apps/{app_id_or_name}/domains/{domain_id} — カスタムドメインを削除します。

DELETE /apps/{app_id_or_name}/domains — アプリからすべてのカスタムドメインを削除します。

Dyno

実行中のプロセスを確認・管理します。

GET /apps/{app_id_or_name}/dynos/list — すべてのDynoと現在の状態を一覧表示します。

DELETE /apps/{app_id_or_name}/dynos — アプリのすべてのDynoを再起動します。

DELETE /apps/{app_id_or_name}/dynos/{dyno} — 特定のDynoを再起動します。

POST /apps/{app_id_or_name}/dynos/{dyno}/exec — 実行中のDyno内でコマンドを実行します。コマンドは文字列の配列で指定します（例：["/bin/sh", "-c", "rails console"]）。

ネームスペース

ネームスペースは、アプリのグループごとに分離された環境を提供します。

GET /namespaces — アクセスできるすべてのネームスペースを一覧表示します。

POST /namespaces — 新しいネームスペースを作成します。nameは必須、team_id、description、regionは省略できます。

GET /namespaces/{namespace_id_or_name} — 特定のネームスペースの詳細を取得します。

DELETE /namespaces/{namespace_id_or_name} — ネームスペースを削除します。

パイプライン

パイプラインは、開発の各ステージ（レビューアプリ、CI、ステージング、本番環境）にわたってアプリをつなぎます。

GET /pipelines — アクセスできるすべてのパイプラインを一覧表示します。

GET /pipelines/{pipeline_id_or_name} — 特定のパイプラインの詳細（環境、レビューアプリの設定など）を取得します。

GET /pipelines/{pipeline_id_or_name}/apps — パイプライン内のすべてのアプリを一覧表示します。

環境

パイプライン環境（レビューアプリのデフォルトなど）のConfig Varを管理します。

GET /environments/{id} — 環境のConfig Varを一覧表示します。

PATCH /environments/{id} — 環境のConfig Varを設定または更新します。キーの値をnullにすると、そのキーは削除されます。

DELETE /environments/{id}/{key} — 環境から特定のConfig Varを削除します。

チーム

チームは、ユーザーとリソースをまとめるグループです。

GET /teams — 所属しているすべてのチームを一覧表示します。

GET /teams/{id} — 特定のチームの詳細を取得します。

アイデンティティ

GET /me — 現在認証されているユーザーのメールアドレスを返します。認証情報が有効かどうかの確認に使えます。

OIDCログイン

GET /oidc-login — Build.ioのクラスターで認証するためのKubernetes ExecCredentialを返します。クエリパラメータregionが必要です。主にCLIがクラスターにアクセスするときに使います。