公開APIとは

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

公開APIは、ベースマキナのリソースを外部システムから操作するためのREST APIです。アクションの一覧取得・詳細取得・実行を、HTTPリクエストで行なえます。

主なユースケースは以下の通りです。

外部システムからベースマキナのアクションを実行する
CI/CDのジョブからアクションを呼び出して定型作業を自動化する
自社のスクリプトやツールに、ベースマキナのアクションを組み込む

ベースURL

https://platform.basemachina.com/public/v1

すべてのエンドポイントはこのベースURLからの相対パスで指定します。

利用できるエンドポイント

エンドポイント	説明
`GET /environments/{environment_id}/actions`	アクションの一覧を取得する
`GET /environments/{environment_id}/actions/{action_id}`	アクションの詳細（引数スキーマなど）を取得する
`POST /environments/{environment_id}/actions/{action_id}/executions`	アクションを同期実行して結果を取得する

現時点で利用できるのは上記3つのアクション系エンドポイントのみです。対応リソースは今後のアップデートで順次追加予定です。

認証

公開APIはBearerトークン認証で保護されています。すべてのリクエストにAuthorizationヘッダーを付与してください。

Authorization: Bearer <token>

利用できるトークンは以下の2種類です。

トークンの種類	取得方法	主な用途
`bm login`で取得したJWT	`bm login`で発行され、`~/.basemachina/credentials.json`に保存される	ローカル端末からの呼び出し、開発時の検証
外部OIDC ID Token	GitHub Actionsなど、ベースマキナのOIDC信頼ポリシーで受け入れ設定済みの発行元から取得	CI/CDからの呼び出し

外部OIDC ID TokenをそのままAuthorization: Bearerに指定すると、公開APIが内部でサービスアカウントのJWTに交換します。事前にOIDC信頼ポリシーの設定が必要です。

Authorizationヘッダーが欠けている場合や、トークンが期限切れ・改ざんなどで検証できない場合は、401 unauthorizedが返ります。

必須ヘッダー

すべてのリクエストに以下のヘッダーを設定してください。

ヘッダー	必須	説明
`Authorization`	必須	`Bearer <token>`形式の認証ヘッダー
`Basemachina-Project`	必須	操作対象のプロジェクトID（`prj_`で始まるULID）。欠落すると`400 bad_request`を返す
`Content-Type`	POST時のみ必須	`application/json`を指定する

アクションの識別子

公開APIではアクションをIDで参照します。IDは管理画面で表示される識別子、またはコード管理でのdefineAction({ id: ... })で指定した文字列と同じです。

bmrn://形式の内部参照IDは受け付けません。指定すると400 bad_requestが返ります。

ページネーション

一覧取得系のエンドポイント（GET /actions）はカーソル形式のページネーションに対応しています。

パラメータ	種別	説明
`limit`	クエリ	1ページあたりの取得件数。`1`〜`100`の整数で、デフォルトは`20`
`cursor`	クエリ	前ページのレスポンスの`next_cursor`を不透明な値としてそのまま指定する

レスポンスは以下のenvelope形式で返ります。次ページの取得情報はレスポンスボディのnext_cursorに含まれ、専用のヘッダーは付与されません。

{
  "data": [
    /* リソース配列 */
  ],
  "has_more": true,
  "next_cursor": "..."
}

has_moreがfalseの場合は次ページがなく、next_cursorは省略されます。

エラーレスポンス

エラー時のレスポンスはRFC 9457 Problem Details (opens in a new tab)形式（Content-Type: application/problem+json）で返ります。

{
  "type": "https://docs.basemachina.com/preview/public_api/#argument_invalid",
  "title": "Argument Invalid",
  "status": 422,
  "detail": "user_id は必須項目です",
  "instance": "/public/v1/environments/env_01H.../actions/send_email/executions",
  "code": "argument_invalid",
  "violations": [{ "field": "arguments.user_id", "reason": "required" }]
}

主なフィールドは以下の通りです。

フィールド	説明
`type`	エラー種別を表すURI。エラーコードごとに固定
`title`	エラー種別の人間可読な短いタイトル
`status`	HTTPステータスコード
`detail`	エラーの詳細メッセージ（運用者向けの自然文）
`instance`	エラーが発生したリクエストのパス
`code`	エラー分類コード。詳細は下表「エラーコード一覧」を参照
`violations`	引数バリデーション違反の詳細。`field`と`reason`の組で複数返る（`code`が`argument_invalid`の場合のみ）
`datasource`	データソースの応答情報（HTTPステータス・URL・本文の冒頭）。`code`が`datasource_error`の場合のみ
`action_id`	エラーに関係するアクションのID。実行系エンドポイントで返ることがある
`statements`	SQL系アクションのステートメントごとの実行結果。一部のSQL関連エラーで返る

エラーコード一覧

codeはHTTPステータスごとに以下のいずれかが返ります。

ステータス	`code`	主な発生条件
`400`	`bad_request`	`Basemachina-Project`欠落、`bmrn://`形式のID指定など、リクエストの文法レベルの不正
`401`	`unauthorized`	Bearerトークン欠落・期限切れ・検証失敗
`403`	`forbidden`	対象プロジェクトやアクションへの権限不足、サービスアカウントから実行できない操作の呼び出しなど
`404`	`not_found`	アクション・環境などのリソースが存在しない、または無効化されている
`405`	`method_not_allowed`	許可されていないHTTPメソッドの利用
`409`	`state_conflict`	アクションの状態不整合
`413`	`payload_too_large`	リクエストボディのサイズ超過
`415`	`unsupported_media_type`	`Content-Type`が`application/json`以外
`422`	`argument_invalid`	引数のバリデーション違反、または公開APIから実行できないアクション種別（旧JavaScriptアクション・fileパラメータを含む）
`422`	`javascript_action_error`	JavaScriptサーバーアクションのコードが投げた業務エラー
`500`	`internal_error`	gateway内部の不具合
`502`	`datasource_error`	データソースなど上流の非成功応答
`503`	`service_unavailable`	ベースマキナ側の一時障害。`Retry-After`ヘッダーに従ってリトライ可能

利用までの流れ

ベースマキナの管理画面で、必要ならOIDC信頼ポリシーを設定する
ローカルからはbm login、CI/CDからは外部OIDC ID Tokenを取得する
プロジェクトIDと環境IDを確認し、Basemachina-Projectヘッダー・パスパラメータに指定する
アクション一覧でアクションのIDを確認する
アクション詳細で引数スキーマを取得し、必要な値を組み立てる
アクション実行でアクションを呼び出す

今後追加予定の機能アクション一覧