API — vue d'ensemble
Piloter vos services depuis vos scripts, votre CI, ou votre propre interface.
L'API REST expose les mêmes actions que le panel : services, conteneurs LXC, sites Pages, stockage objet, bases de données. Tout se fait en HTTPS, avec une clé d'API en en-tête et du JSON dans les deux sens (à l'exception de l'envoi de fichiers, en corps brut — voir la référence).
Adresse de base#
https://api.ecloudserv.fr/api/v1Tous les chemins de la référence sont relatifs à cette base : /servers désigne donc https://api.ecloudserv.fr/api/v1/servers.
Authentification#
Chaque requête porte votre clé dans l'en-tête Authorization, sous la forme Bearer :
curl https://api.ecloudserv.fr/api/v1/me \
-H "Authorization: Bearer VOTRE_CLE"Créer une clé et choisir ses portées : voir Clés d'API.
Portées#
| Portée | Ce qu'elle autorise |
|---|---|
read | Consulter : compte, liste des services, état, ressources. |
write | Agir : créer un service, l'allumer, l'éteindre, le modifier. |
Astuce
Format des réponses#
Les réponses sont en JSON. Le code HTTP porte le résultat : 2xx en cas de succès, 4xx si la requête est en cause, 5xx si c'est nous.
| Code | Signification | Que faire |
|---|---|---|
| 200 | Succès | — |
| 201 | Ressource créée | — |
| 401 | Clé absente ou invalide | Vérifier l'en-tête Authorization. |
| 403 | Portée insuffisante | La clé n'a pas la portée write, par exemple. |
| 404 | Ressource introuvable | Vérifier l'identifiant du service. |
| 429 | Trop de requêtes | Ralentir, puis réessayer. |
| 5xx | Erreur côté serveur | Réessayer plus tard ; signaler si ça persiste. |
Bonnes pratiques#
- Stockez la clé dans une variable d'environnement, jamais dans le dépôt — voir Variables & secrets.
- Sur un
429, attendez avant de réessayer, en allongeant progressivement le délai. Réessayer immédiatement en boucle ne fait qu'aggraver la situation. - Ne partez pas du principe qu'une action est instantanée : un démarrage prend un certain temps. Interrogez l'état plutôt que de supposer.
Une clé fuitée donne accès à vos services