REST API リファレンス

Cockpit API を使用すると、外部の別のプログラムや自作の自動化スクリプトなどから、仮想マシンの操作、パフォーマンス情報の取得、クラスターの管理などを自動で行えるようになります。

---

1. API と JWT トークンとは？ 🔌

💡 たとえ話：銀行のドライブスルー窓口

• REST API: 銀行のドライブスルー窓口をイメージしてください。わざわざ車から降りてロビー（Web管理画面）に入ることなく、車に乗ったまま窓口のポストに申請用紙（HTTPリクエスト）を投函すれば、行員が要望を処理して現金や明細書（JSONレスポンス）を返してくれます。これにより、自動運転車（自動スクリプト）が直接銀行を利用できるようになります。
• JWT (デジタル入館証): 最初に窓口に行って「私は管理者です」と証明（ログイン）すると、行員から時間制限タイマー付きのデジタル入館証（JWTトークン）が渡されます。これ以降は、手続きのポストに申請用紙を出すたびに、この入館証（Authorization: Bearer <JWT_TOKEN>）を提示して、権限があることを証明します。

---

2. 認証方式 (Authentication)

すべての API リクエストには、HTTP ヘッダーにこのデジタル入館証（トークン）を同封する必要があります：

Authorization: Bearer <取得したJWTトークン>
Content-Type: application/json

ログインして入館証 (トークン) を取得する

• リクエスト: 管理者のログイン情報を送信します。

POST /api/v1/auth/login

• 送るデータ (JSON Payload):

  {
    "username": "admin",
    "password": "yourpassword"
  }

• 返ってくるデータ (JSON Response):

  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // <-- これが入館証（トークン）です
    "refresh_token": "a1b2c3d4-...",
    "expires_in": 3600 // 有効期限 (秒数 - 1時間)
  }

期限切れの入館証を新しくする

• リクエスト: 入館証の期限が切れた場合、更新用トークン（refresh_token）を提示して新しい入館証を発行してもらいます。

POST /api/v1/auth/refresh

• 送るデータ:

  {
    "refresh_token": "a1b2c3d4-..."
  }

---

3. 物理サーバーの管理

登録されているすべてのサーバーの一覧を取得

• リクエスト:

GET /api/v1/hosts

• 返ってくるデータ:

  {
    "hosts": [
      {
        "id": "019e0014-abcd-7057-b326-000000000001",
        "hostname": "vapor-node-01.corp.awan.io",
        "status": "connected",
        "sync_cursor": 1716999901
      }
    ]
  }

---

4. 仮想マシンの管理

クラスター内のすべての VM を一覧表示

• リクエスト:

GET /api/v1/vms

仮想マシンの電源操作

• リクエスト: 特定の VM の ID を指定して、起動・停止・再起動などのアクションを要求します。

POST /api/v1/vms/:id/action

• 送るデータ:
  • 起動する場合: {"action": "start"}
  • 強制停止（電源プラグ引き抜き）する場合: {"action": "stop", "force": true}

仮想マシンを別の物理サーバーへ移動 (ライブマイグレーション)

• リクエスト: 動いている仮想マシンを別の物理サーバーへ引っ越しさせます。

POST /api/v1/vms/:id/migrate

• 送るデータ:

  {
    "destination_host_id": "019e0014-ffff-7057-b326-000000000002", // 移動先物理サーバーのID
    "live": true,          // 動かしたまま移動させる
    "persistent": true,    // 移動先にVM設定を永続的に保存する
    "undefine_source": true, // 移動完了後、元のサーバーから設定を消去する
    "copy_storage": "none" // 共有ストレージを使用している場合は "none" を指定
  }

• 返ってくるデータ:

  {
    "migration_id": "abc123def456",
    "status": "initiated"
  }