Build APIリファレンス
Build APIを使うと、アプリや設定、プラットフォームのリソースにプログラムからアクセスできます。Build.ioをCI/CDパイプラインに組み込んだり、デプロイを自動化したり、独自のツールを作ったりするときに使います。
インタラクティブドキュメント
Section titled “インタラクティブドキュメント”リクエストとレスポンスの詳しいスキーマは、Swaggerドキュメントで確認できます。エンドポイントをその場で呼び出して試すこともできます:
https://app.build.io/api-docs/index.html
HTTPのBasic認証を求められたら、ユーザー名にbuild、パスワードにbestを入力します。
ベースURL
Section titled “ベースURL”APIリクエストはすべて次のURLに送信します:
APIは複数の認証方式に対応しています。ほとんどの場合、Bearerトークンを使う方法が最も簡単です。
トークンはAuthorizationヘッダーに指定します:
Authorization: Bearer your-token-hereAPIトークンに有効期限はありません。アカウント設定から取り消すまで有効であり続けるため、ローテーションは手動で行います。新しいトークンを生成し、利用している箇所をすべて切り替えたうえで、古いトークンを取り消してください。同じトークンで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が返されます。再試行の前に間隔を空け、大量の操作は一度にまとめず分散して実行してください。
リソースの概要
Section titled “リソースの概要”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
Section titled “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: アプリからすべてのカスタムドメインを削除します。
実行中のプロセスを確認・管理します。
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"])。
ネームスペース
Section titled “ネームスペース”ネームスペースは、アプリのグループごとに分離された環境を提供します。
GET /namespaces: アクセスできるすべてのネームスペースを一覧表示します。
POST /namespaces: 新しいネームスペースを作成します。nameは必須、team_id、description、regionは省略できます。
GET /namespaces/{namespace_id_or_name}: 特定のネームスペースの詳細を取得します。
DELETE /namespaces/{namespace_id_or_name}: ネームスペースを削除します。
パイプライン
Section titled “パイプライン”パイプラインは、開発の各ステージ(レビューアプリ、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}: 特定のチームの詳細を取得します。
アイデンティティ
Section titled “アイデンティティ”GET /me: 現在認証されているユーザーのメールアドレスを返します。認証情報が有効かどうかの確認に使えます。
OIDCログイン
Section titled “OIDCログイン”GET /oidc-login: Build.ioのクラスターで認証するためのKubernetes ExecCredentialを返します。クエリパラメータregionが必要です。主にCLIがクラスターにアクセスするときに使います。
