casaのための、一つの契約

機械可読の契約

GET /api/v1/openapi.jsonは、このデプロイで実装されている内容を正確に示すOpenAPI 3.1文書を返します。すべてのパス、スキーマ、必要なスコープ、レスポンス、Webhookイベントを含みます。MCPツールも生成する、実行中の同じ操作カタログから生成されるため、RESTとMCPの仕様がずれることはありません。

curl -s "https://<your host>/api/v1/openapi.json"

対象はcasaと下書き、リビジョンと公開、投稿、テンプレートカタログ、インポート、ポートフォリオと一括実行、ドメインとDNS計画、メール転送、登録と問い合わせの設定、ソーシャルソース、アクセス解析、プロモーション、課金、チームメンバー、Webhookです。GET /workspaces/{id}/capabilitiesで、ワークスペース内のどれが稼働中、シミュレーション、認証情報待ちかがわかります。

再試行は意図して行う

• どの変更操作にも16～128文字のIdempotency-Keyヘッダーが必要です。同じキーと本文でリクエストを繰り返すと、Idempotent-Replayed: true付きで元の結果を返します。同じキーに異なる本文を使うと409 idempotency_key_reusedになります。
• casaの編集には、最後の読み取りのIf-MatchとETagの組み合わせが必要です。古い値の場合は412 revision_conflictになり、何も変更されません。
• 公開には、読み取った正確なrevision_idとexpected_digestを渡します。これで確認したものを公開できます。

時間のかかる処理はジョブになる

公開、一括実行、その他の遅い操作は、ジョブを伴う202を返します。GET /workspaces/{id}/jobs/{job_id}へのポーリングはnext_poll_after_seconds以上の間隔を空けるか、job.updatedのWebhookを購読してください。受け付けは完了ではありません。成功を報告する前に、ジョブのstate、件数、errorを読んでください。

エラーは問題の詳細を返す

エラーはapplication/problem+json形式で、安定したcode、ローカライズされたtitle、request_id、retryableを含みます。分岐にはcodeを使い、タイトルの文章では判定しないでください。

{
  "type": "https://<your host>/problems/insufficient_scope",
  "title": "This token does not include the permission this action needs.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

一覧と上限

• 一覧エンドポイントはlimit（最大100）と、前のページのcursorを受け取ります。
• 各ワークスペーストークンは、一分間に120回の読み取りと30回の書き込みができます。上限を超えると、429とRetry-Afterヘッダーを返します。
• 未知のレスポンスフィールドも保持してください。バージョン変更なしで新しいフィールドが加わることがあります。