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. Tout se fait en HTTPS, avec une clé d'API en en-tête et du JSON dans les deux sens.
Adresse de base#
base URL
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 :
première requête
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
Donnez à chaque clé le strict nécessaire. Un script de supervision qui ne fait que lire n'a aucune raison de pouvoir supprimer un service.
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
Si vous pensez qu'une clé a été exposée — commit public, capture d'écran, log partagé — révoquez-la immédiatement et créez-en une autre. La révocation prend effet tout de suite.