公開APIとは

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

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

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

ベースURL

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

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

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

認証

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

Authorization: Bearer <token>

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

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

ヘッダー

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

プロジェクトと環境の指定

操作対象のプロジェクトと環境は、URLパスのproject_idとenvironment_idで指定します。

/projects/{project_id}/environments/{environment_id}

アクションの識別子

公開APIではアクションをIDで参照します。IDは管理画面で表示される識別子、またはコード管理でのdefineAction({ id: ... })で指定した文字列と同じです。アクション一覧・詳細のレスポンスに含まれるidを、そのまま実行時のaction_idに指定してください。

ページネーション

アクション一覧エンドポイント（GET /projects/{project_id}/environments/{environment_id}/actions）はカーソル形式のページネーションに対応しています。

レスポンスは以下の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/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions",
  "code": "argument_invalid",
  "violations": [{ "field": "arguments.user_id", "reason": "required" }]
}

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

エラーコード一覧

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

利用までの流れ

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