Referensi API REST

API Cockpit memungkinkan program perangkat lunak lain dan skrip kustom untuk mengontrol mesin virtual, memeriksa log kinerja, dan mengelola server secara otomatis.

---

1. Apa itu API & Token JWT? 🔌

💡 Analogi: Loket Drive-Through Bank

• REST API: Bayangkan seperti loket drive-through di bank. Alih-alih masuk ke dalam lobi kantor (menggunakan dashboard web), Anda mengendarai mobil ke loket, menyerahkan formulir transaksi lewat celah kaca (permintaan HTTP), lalu petugas menyerahkan uang atau tanda terima kepada Anda (tanggapan JSON). Hal ini memungkinkan program lain atau skrip otomatis untuk mengelola Cockpit secara langsung.
• JWT (Kartu Akses Pengaman): Ketika pertama kali tiba di loket dan membuktikan identitas Anda (login), petugas memberikan kartu akses pengenal digital (token JWT) yang memiliki batas waktu (kedaluwarsa). Setiap kali Anda datang kembali ke loket untuk melakukan transaksi, Anda harus menunjukkan kartu akses ini (Authorization: Bearer <JWT_TOKEN>) agar petugas tahu Anda memiliki izin.

---

2. Autentikasi

Semua permintaan API harus menyertakan kartu akses pengenal Anda di dalam header permintaan HTTP:

Authorization: Bearer <TOKEN_JWT_ANDA>
Content-Type: application/json

Masuk untuk Mendapatkan Kartu Akses (Token)

• Permintaan: Kirim kredensial admin Anda.

POST /api/v1/auth/login

• Payload (Data JSON yang Anda kirim):

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

• Tanggapan (Data JSON yang Anda terima):

  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // <-- Ini kartu akses pengaman Anda
    "refresh_token": "a1b2c3d4-...",
    "expires_in": 3600 // Kedaluwarsa dalam detik (1 jam)
  }

Memperbarui Kartu Akses yang Kedaluwarsa

• Permintaan: Jika kartu akses Anda habis masa berlakunya, tukarkan token pembaruan (refresh token) Anda dengan kartu akses baru.

POST /api/v1/auth/refresh

• Payload:

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

---

3. Mengelola Server Fisik

Menampilkan Semua Server Terdaftar

• Permintaan:

GET /api/v1/hosts

• Tanggapan:

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

---

4. Mengelola Mesin Virtual

Menampilkan Semua Mesin Virtual di Klaster

• Permintaan:

GET /api/v1/vms

Mengontrol Daya Mesin Virtual

• Permintaan: Menyalakan, mematikan, atau menyalakan ulang VM tertentu berdasarkan ID-nya.

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

• Payload:
  • Menyalakan VM: {"action": "start"}
  • Mematikan paksa VM (cabut kabel daya): {"action": "stop", "force": true}

Memindahkan VM ke Server Lain (Migrasi Langsung)

• Permintaan: Memindahkan VM yang sedang berjalan ke server fisik lain.

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

• Payload:

  {
    "destination_host_id": "019e0014-ffff-7057-b326-000000000002", // ID server fisik tujuan
    "live": true,          // Lakukan migrasi tanpa mematikan VM
    "persistent": true,    // Simpan konfigurasi VM secara permanen di server tujuan
    "undefine_source": true, // Hapus konfigurasi VM dari server asal setelah selesai
    "copy_storage": "none" // Setel ke "none" jika kedua server menggunakan penyimpanan bersama
  }

• Tanggapan:

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