API Dokumentace

REST API pro programovou správu virtuálních serverů na platformě VPS.cz.

Base URL https://api.vps.cz/api

API používá standardní HTTP metody a vrací odpovědi ve formátu JSON. Všechny požadavky musí být autentizovány pomocí Bearer tokenu nebo API klíče.

Autentizace

API podporuje dva způsoby autentizace:

Bearer Token (JWT)

Získejte token přihlášením a použijte ho v hlavičce:

POST /api/auth/login

curl -X POST https://api.vps.cz/api/auth/login \
  -d "username=vas_email@example.com" \
  -d "password=vase_heslo"

Odpověď:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Použití tokenu:

curl https://api.vps.cz/api/vms \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API klíč

Pro dlouhodobý programový přístup vygenerujte API klíč:

POST /api/auth/api-key

curl -X POST https://api.vps.cz/api/auth/api-key \
  -H "Authorization: Bearer $TOKEN"

Použití API klíče:

curl https://api.vps.cz/api/vms \
  -H "X-API-Key: vas_api_klic"

Chybové kódy

API používá standardní HTTP stavové kódy:

Kód	Význam
`200`	Úspěšný požadavek
`201`	Zdroj vytvořen
`204`	Úspěšné smazání
`400`	Neplatný požadavek
`401`	Neautorizovaný přístup
`403`	Přístup zamítnut
`404`	Zdroj nenalezen
`500`	Interní chyba serveru

Chybová odpověď:

{
  "detail": "Popis chyby"
}

Seznam virtuálních serverů

GET /api/vms

curl https://api.vps.cz/api/vms \
  -H "Authorization: Bearer $TOKEN"

Query parametry

Parametr	Typ	Popis
`page`	integer	Číslo stránky (výchozí: 1)
`per_page`	integer	Položek na stránku (výchozí: 20)
`status_filter`	string	Filtr: running, stopped, error

Odpověď

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-server",
      "display_name": "Produkční web",
      "vcpu_count": 2,
      "ram_mb": 4096,
      "status": "running",
      "ip_address": "203.0.113.42",
      "primary_disk_gb": 60,
      "plan_name": "Standard 1",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

Detail VPS

GET /api/vms/{vm_id}

curl https://api.vps.cz/api/vms/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

Vytvoření VPS

POST /api/vms

curl -X POST https://api.vps.cz/api/vms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "muj-server",
    "display_name": "Můj nový server",
    "plan_id": "plan-uuid",
    "os_image_id": "image-uuid",
    "ssh_keys": ["key-uuid-1", "key-uuid-2"],
    "password": "silne_heslo_123"
  }'

Parametry požadavku

Pole	Typ	Povinné	Popis
`name`	string	Ano	Hostname (3-64 znaků, malá písmena, čísla, pomlčky)
`display_name`	string	Ne	Zobrazovaný název
`plan_id`	uuid	Ano*	ID plánu (nebo ruční konfigurace)
`vcpus`	integer	Ne	Počet vCPU (1-32)
`ram_mb`	integer	Ne	RAM v MB (512-131072)
`disk_gb`	integer	Ne	Disk v GB (10-2048)
`os_image_id`	uuid	Ne	ID OS image
`ssh_keys`	array	Ne	Seznam ID SSH klíčů
`password`	string	Ne	Root heslo
`user_data`	string	Ne	Cloud-init skript

Odpověď (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "muj-server",
  "status": "provisioning",
  "ip_address": "203.0.113.42",
  ...
}

Úprava VPS

PUT /api/vms/{vm_id}

curl -X PUT https://api.vps.cz/api/vms/{vm_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Nový název", "vcpus": 4, "ram_mb": 8192}'

Smazání VPS

DELETE /api/vms/{vm_id}

curl -X DELETE https://api.vps.cz/api/vms/{vm_id} \
  -H "Authorization: Bearer $TOKEN"

Akce s VPS

POST /api/vms/{vm_id}/action

curl -X POST https://api.vps.cz/api/vms/{vm_id}/action \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "start"}'

Dostupné akce

Akce	Popis
`start`	Spustit server
`stop`	Graceful shutdown
`reboot`	Restart serveru
`force_stop`	Vynucené vypnutí
`suspend`	Pozastavit
`resume`	Obnovit z pozastavení

Statistiky VPS

Aktuální statistiky

GET /api/vms/{vm_id}/stats

curl https://api.vps.cz/api/vms/{vm_id}/stats \
  -H "Authorization: Bearer $TOKEN"

Odpověď

{
  "cpu_usage_percent": 23.5,
  "memory_used_mb": 2048,
  "memory_total_mb": 4096,
  "disk_read_bytes": 1048576,
  "disk_write_bytes": 524288,
  "network_rx_bytes": 10485760,
  "network_tx_bytes": 5242880,
  "uptime_seconds": 86400
}

Historické statistiky

                            GET
                            /api/vms/{vm_id}/stats/history?hours=24
                        

VNC konzole

GET /api/vms/{vm_id}/console

curl https://api.vps.cz/api/vms/{vm_id}/console \
  -H "Authorization: Bearer $TOKEN"

Odpověď

{
  "vnc_host": "console.vps.cz",
  "vnc_port": 5900,
  "vnc_password": "abc123xyz",
  "websocket_url": "/api/ws/vnc/{vm_id}"
}

Snapshoty

Každý VPS může mít maximálně 2 snapshoty.

Seznam snapshotů

                            GET
                            /api/vms/{vm_id}/snapshots
                        

Vytvoření snapshotu

POST /api/vms/{vm_id}/snapshots

curl -X POST https://api.vps.cz/api/vms/{vm_id}/snapshots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "pred-aktualizaci", "description": "Záloha před update"}'

Obnovení ze snapshotu

                            POST
                            /api/vms/{vm_id}/snapshots/{snapshot_id}/restore
                        

VPS musí být vypnutý pro obnovení ze snapshotu.

Smazání snapshotu

                            DELETE
                            /api/vms/{vm_id}/snapshots/{snapshot_id}
                        

SSH klíče

Seznam SSH klíčů

                            GET
                            /api/vms/ssh-keys
                        

Přidání SSH klíče

POST /api/vms/ssh-keys

curl -X POST https://api.vps.cz/api/vms/ssh-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Můj notebook",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host"
  }'

Podporované typy klíčů

ssh-rsa
ssh-ed25519
ecdsa-sha2-nistp256/384/521

Smazání SSH klíče

                            DELETE
                            /api/vms/ssh-keys/{key_id}
                        

Plány a OS obrazy

Dostupné plány

                            GET
                            /api/vms/plans
                        

Odpověď

[
  {
    "id": "plan-uuid",
    "name": "starter-1",
    "display_name": "Starter 1",
    "vcpu_count": 1,
    "ram_mb": 1024,
    "disk_gb": 20,
    "price_monthly": 99,
    "price_currency": "CZK"
  },
  ...
]

Dostupné OS obrazy

                            GET
                            /api/vms/images
                        

Odpověď

[
  {
    "id": "image-uuid",
    "name": "Ubuntu 24.04 LTS",
    "os_family": "debian",
    "os_name": "Ubuntu",
    "os_version": "24.04",
    "cloud_init_supported": true
  },
  ...
]

WebSocket API

Real-time události

Připojte se k WebSocket pro real-time aktualizace:

wss://api.vps.cz/api/ws/events?token=JWT_TOKEN

Přihlášení k odběru statistik VPS

// Odeslat
{"type": "subscribe_vm", "vm_id": "vm-uuid"}

// Odpověď každých 5 sekund
{
  "type": "vm_stats",
  "vm_id": "vm-uuid",
  "data": {
    "cpu_usage_percent": 23.5,
    "memory_used_mb": 2048,
    ...
  }
}

VNC přes WebSocket

Pro noVNC klienta:

wss://api.vps.cz/api/ws/vnc/{vm_id}?token=JWT_TOKEN