コンテンツにスキップ

Build APIリファレンス

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

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

Section titled “インタラクティブドキュメント”

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

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

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

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

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

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

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

Authorization: Bearer your-token-here

APIトークンに有効期限はありません。アカウント設定から取り消すまで有効であり続けるため、ローテーションは手動で行います。新しいトークンを生成し、利用している箇所をすべて切り替えたうえで、古いトークンを取り消してください。同じトークンでAPIとbld CLIの両方を認証します。

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

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

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

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

OAuthクライアントの認証情報はセルフサービスでは発行できません。クライアントの登録は管理者に限られているため、必要な場合はsupport@build.ioまでご連絡ください。CI/CD連携やカスタムツールの開発を含むそれ以外の用途では、アカウント設定から生成したBearerトークンをご利用ください。

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

Section titled “リクエストとレスポンスの形式”

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

Content-Type: application/json

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

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

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

APIにはフェアユースに基づくレート制限があり、IPアドレス単位で適用されます。公開された固定の上限値はなく、しきい値は時期によって変わります。

制限を超えたリクエストにはHTTP 429が返されます。再試行の前に間隔を空け、大量の操作は一度にまとめず分散して実行してください。

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(アプリに環境変数として渡される設定値)を管理します。

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: アプリからすべてのカスタムドメインを削除します。

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

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: 現在認証されているユーザーのメールアドレスを返します。認証情報が有効かどうかの確認に使えます。

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