basemachina BaseMachina 公開API
公開APIはBaseMachinaのresourceを外部systemから操作するREST API。現在のendpoint、request・response、error codeは記憶で書かず、公式ガイド、API reference、OpenAPI schemaを都度確認する。
対象
- 有効な環境の一覧取得
- actionの一覧・詳細取得
- review不要actionの実行
- review必須actionに対するreview依頼の作成・状態取得・承認後実行
bm loginのJWTまたは外部OIDC ID Token交換による認証- response・error処理、OpenAPIからのclient生成
action・datasourceなどの設定作成・編集・削除は公開APIの対象外。管理画面またはbm-code-managementを使う。
Guardrail
action実行には、mail送信、DB書き込み、外部service呼び出しなど取り消せない副作用がありうる。review依頼の作成も承認workflowや通知を開始しうる。
- APIを呼び出すcodeだけを書く。実際のrequest、特に
executionsとreview依頼作成はユーザーまたはCIに委ねる allowed-toolsにcurlなどのHTTP実行toolを含めない- 引き渡し時に対象環境・action・引数・想定される副作用を明記する
- retryを一律に実装しない。HTTP method、idempotency、副作用、現在のAPI referenceを確認して判断する
Workflow
- 対象project、環境、actionを特定する。actionは識別子またはaction IDで参照する
- 公開APIから実行できないactionに該当しないか確認する
- local検証なら
bm login+bm print-access-tokenで取り出すJWT、CI・cloudなら外部OIDC ID Token交換を選ぶ - method、path、query、request・response schemaをOpenAPIで確認してcodeを書く
- review不要actionはexecution endpointを使う。review必須actionは直接実行すると
403 forbiddenになるため、review依頼を作成し、状態を取得して、承認済みかつ自動実行されていない場合にreview依頼のexecution endpointを使う auto_execute_on_approvalを指定する場合は、承認後に誰が実行する設計かを明確にし、二重実行を避ける- 通常endpointのRFC 9457 Problem Detailsと、
/tokenのOAuth error responseを分けて処理する - 変更file、endpoint、環境・action ID、引数、副作用、認証前提、ユーザーまたはCIへ残した動作確認を報告する
認証
/token以外のendpointはAuthorization: Bearer <token>で保護される。
- local開発:
bm loginでJWTが~/.basemachina/credentials.jsonに保存される。bm print-access-tokenがそのJWTを標準出力に出すので、export BM_TOKEN=$(bm print-access-token)のように環境変数へ渡してBearer tokenに使う。credentials.jsonを直接読むcodeは書かない。browser対話flowは自動化せず、未loginならユーザーにbm loginを依頼する - CI/CD・cloud・自社IdP: 外部OIDC ID Tokenをそのまま送らず、
/tokenでBaseMachina access tokenへ交換する。事前にprojectへのservice account割り当てとOIDC trust policyが必要
ID Token取得、token交換のrequest・response、Issuer・Audience・Bound Claimsは認証ガイドとservice accountで確認する。access tokenはexpires_inまで再利用し、期限切れ後に再交換する。bm print-access-tokenは未loginだとexit code 1で失敗し、tokenの有効期限も検証しない。期限切れのまま渡すと公開API側で401になるので、401が返ったらbm loginをやり直す。