Virtana / Documentation / API
Pilotez vos conteneurs depuis vos scripts.
Une API JSON authentifiée par jetons d’accès personnels : liste et état des conteneurs, démarrage, arrêt, sauvegardes, opérations et mesures.
01Créer un jeton d’accès
Un jeton d’accès personnel permet à un script, à une intégration continue ou à un outil de supervision de consulter vos conteneurs et, si vous l’autorisez, de les démarrer, les arrêter, les redémarrer, les sauvegarder ou d’en prendre un instantané.
-
Ouvrez votre compte, section « Jetons d’accès à l’API ».
-
Donnez un nom au jeton, puis choisissez ses droits (lecture seule, ou lecture et actions), sa durée (30, 90 ou 365 jours, ou sans expiration) et, si vous le souhaitez, les conteneurs auxquels il est limité.
-
Copiez le jeton affiché : il commence par
vtn_et n’est montré qu’une fois. Virtana n’en garde qu’une empreinte (SHA-256) : un jeton perdu se remplace par un nouveau.
- Le jeton agit avec vos droits : sur vos conteneurs et sur ceux partagés avec vous, dans la limite des permissions que leur propriétaire vous a données.
- Révoquez-le depuis la même page dès qu’il ne sert plus ou s’il a pu fuiter : il est refusé dès la requête suivante.
- Un compte suspendu ne peut plus utiliser ses jetons.
- La page indique, pour chaque jeton, sa dernière utilisation et le nombre d’actions demandées.
Gardez le jeton comme un mot de passe : dans un gestionnaire de secrets ou une variable d’environnement, jamais dans un dépôt Git.
Retour au sommaire02Authentification et erreurs
Toutes les adresses commencent par https://virtana.fr/api/v1. Le jeton passe dans l’en-tête Authorization, sans session ni cookie.
Vérifiez votre jeton : la réponse donne son nom, ses droits, ses conteneurs et son expiration.
export VIRTANA_TOKEN="vtn_…"
curl -s https://virtana.fr/api/v1/token -H "Authorization: Bearer $VIRTANA_TOKEN"Les réponses sont en JSON. Une ressource se trouve dans data. Une erreur a toujours la même forme :
{"error": {"code": "token_expired", "message": "Ce jeton d’accès a expiré : créez-en un nouveau depuis votre compte."}}Le champ code est stable et destiné à vos programmes. Le champ message suit l’en-tête Accept-Language : français par défaut, ou anglais. Un refus de validation ajoute details, champ par champ.
401: jeton absent (unauthenticated), inconnu (invalid_token), expiré (token_expired) ou révoqué (token_revoked).403: jeton en lecture seule (insufficient_scope), permission manquante sur le conteneur (forbidden) ou compte suspendu (account_suspended).404: conteneur ou opération inexistants, ou hors de portée du jeton (container_not_found,operation_not_found).409:Idempotency-Keydéjà utilisée pour une autre action (idempotency_key_reused).422: action refusée par l’état du conteneur, la période payée ou l’offre (action_refused), action absente de l’API (action_not_supported) ou données invalides (validation_failed).429: limite de débit atteinte (rate_limited).
03Lister et consulter vos conteneurs
La liste comprend vos conteneurs et ceux partagés avec vous, ou seulement ceux du jeton s’il est limité. Chaque conteneur a un identifiant id, le même que dans l’adresse de sa fiche.
Lister les conteneurs, 25 par page, jusqu’à 100 avec per_page, et filtrer par état avec state :
curl -s "https://virtana.fr/api/v1/containers?state=running" -H "Authorization: Bearer $VIRTANA_TOKEN"Afficher un conteneur :
curl -s https://virtana.fr/api/v1/containers/ID -H "Authorization: Bearer $VIRTANA_TOKEN"state: état du conteneur (running,stopped,archived,suspended…).resources: processeurs (vcpu), mémoire en Mio (ram_mb) et disque en Go (disk_gb).access: la commande SSH et l’adresse HTTPS, une fois le conteneur publié, si vous avez la permission « Console ».billing.term: échéance, c’est-à-dire la fin de la période payée, ou la date d’arrêt d’un abonnement résilié.roleetpermissions: propriétaire ou collaborateur, et ce que vous pouvez y faire.meta.totaletlinks.next: nombre de conteneurs et page suivante.
04Démarrer, arrêter, sauvegarder
Un jeton « lecture et actions » peut démarrer, arrêter ou redémarrer un conteneur, lancer une sauvegarde ou prendre un instantané. Les contrôles de l’espace client s’appliquent : état du conteneur, période payée, sauvegardes prévues par l’offre, permissions d’un collaborateur.
Chaque action porte un en-tête Idempotency-Key : un UUID que vous générez une fois par action.
curl -s -X POST https://virtana.fr/api/v1/containers/ID/actions \
-H "Authorization: Bearer $VIRTANA_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"action": "restart"}'- Valeurs de
action:start,stop,restart,backupetsnapshot. Commande, paiement, résiliation, réinstallation et restauration restent dans l’espace client. - La réponse
202renvoie l’opération créée, avec sonidet le statutpending, et donne son adresse dans l’en-têteLocation. - La même requête renvoyée avec la même clé, par exemple après une coupure réseau, ne crée pas de seconde opération : vous recevez la première, avec l’en-tête
Idempotent-Replayed: true. Une clé réutilisée pour une autre action est refusée. - Une seule opération à la fois par conteneur : tant qu’une action est en cours, la suivante est refusée.
- Chaque action figure dans le journal du conteneur avec le nom du jeton qui l’a demandée.
05Suivre une opération
Une action se déroule en arrière-plan. Consultez l’opération jusqu’à ce que son status vaille succeeded, failed ou uncertain.
Consulter une opération :
curl -s https://virtana.fr/api/v1/operations/OPERATION_ID -H "Authorization: Bearer $VIRTANA_TOKEN"pending: en file d’attente ;running: en cours ;succeeded: terminée ;failed: échouée, avecerror_code;uncertain: résultat à vérifier par un opérateur.- Pour une sauvegarde ou un instantané,
backupdonne l’identifiant de la copie une fois créée.
Attendre la fin d’une opération dans un script :
until curl -s https://virtana.fr/api/v1/operations/OPERATION_ID -H "Authorization: Bearer $VIRTANA_TOKEN" \
| grep -Eq '"status": ?"(succeeded|failed|uncertain)"'; do sleep 5; done06Sauvegardes et mesures
Deux lectures complètent la fiche d’un conteneur : ses copies conservées et son dernier relevé.
Lister les sauvegardes et les instantanés conservés, du plus récent au plus ancien. Un collaborateur a besoin de la permission de lecture des sauvegardes.
curl -s https://virtana.fr/api/v1/containers/ID/backups -H "Authorization: Bearer $VIRTANA_TOKEN"Lire les dernières mesures : processeur, mémoire, disque et réseau. fresh indique un relevé de moins de cinq minutes.
curl -s https://virtana.fr/api/v1/containers/ID/metrics -H "Authorization: Bearer $VIRTANA_TOKEN"07Limites de débit
Chaque jeton a droit à 60 requêtes par minute, dont 10 actions.
- Les en-têtes
X-RateLimit-LimitetX-RateLimit-Remainingde chaque réponse indiquent votre marge. - Au-delà, la réponse est
429(rate_limited), avec l’en-têteRetry-Afteren secondes. - Trop de jetons invalides envoyés depuis la même adresse la bloquent une minute.
08Spécification OpenAPI
La description complète de l’API, au format OpenAPI 3.1, est publique : openapi.json. Importez-la dans Postman ou Insomnia, ou générez un client dans votre langage.
curl -s https://virtana.fr/api/v1/openapi.json -o virtana-openapi.jsonLes champs de la version 1 ne changeront pas de sens ; de nouveaux champs peuvent s’ajouter. Une évolution incompatible prendra la forme d’une version 2, à une autre adresse.
Retour au sommaire