Référence de l'API REST

L'API HTTP exposée par le démon Saba-chan : schéma d'authentification et catalogue des principaux endpoints.

Référence de l'API REST

Le démon Saba-chan (saba-core) expose une API REST HTTP sur 127.0.0.1:57474. La GUI et la CLI n'appellent que cette API, et les commandes Discord qui arrivent via le relais cloud sont traitées par les mêmes fonctionnalités à l'intérieur du démon. Vous pouvez créer un client personnalisé en suivant le même contrat.

Cette référence résume les routes dont un utilisateur ou un intégrateur aura probablement besoin, tirées des définitions de routes du démon (src/ipc/). Certaines routes internes sont omises, et les schémas des champs peuvent changer ; consultez le code pour la version la plus récente.


1. Généralités

  • URL de base : http://127.0.0.1:57474 (par défaut). Modifiable via la variable d'environnement SABA_IPC_PORT ou gui.ipcPort dans config.json (prend effet après le redémarrage du démon).
  • Adresse d'écoute : fixée à 127.0.0.1, elle n'est donc pas accessible depuis l'extérieur. Les requêtes dont l'en-tête Host n'est pas une adresse de loopback (127.0.0.1, localhost, ::1) reçoivent un 403.
  • Authentification : chaque requête, à l'exception de /health, nécessite un en-tête X-Saba-Token. Le démon génère un nouveau jeton à chaque démarrage et l'écrit dans le fichier .ipc_token du dossier de données (Windows : %APPDATA%\saba-chan\.ipc_token). Un jeton absent ou erroné reçoit un 401 sans corps.
  • Content-Type : les corps de requête sont en application/json. La plupart des réponses sont aussi en JSON (les bundles GUI des extensions, les icônes, etc. font exception).
  • Format des erreurs : varie selon la route. Les formes courantes sont {"error": "...", "error_code": "..."}, {"success": false, "error": ..., "error_code": ...} et {"ok": false, "error": ...}. Certaines routes renvoient HTTP 200 avec ok:false en cas d'échec ; vérifiez donc aussi le corps.

2. Healthcheck et démon

GET  /health                     # aucun jeton requis
GET  /api/version
GET  /api/diagnostics
GET  /api/events                 # flux d'événements (SSE)
POST /api/daemon/shutdown
  • /health : {"ok": true, "version": "x.y.z", "pid": 1234, "token": "valid" | "invalid" | "missing"}. token indique seulement si le X-Saba-Token que vous avez envoyé est correct ; il ne révèle jamais la valeur.
  • /api/version : {version, components: {...}} (versions du cœur, des modules et des extensions).
  • /api/events : Server-Sent Events. Les principaux types sont instance.exit (arrêt du serveur / verdict de crash), backup.done, update.available, schedule.warn, provision.progress et action.run. Lors d'une reconnexion, vous pouvez rattraper les événements manqués avec l'en-tête Last-Event-ID ou ?since=<n>.
  • /api/daemon/shutdown : arrête le démon.

3. Serveurs (instances)

Saba-chan gère chaque serveur comme une instance, identifiée par un UUID (id).

3.1 Lister, créer, modifier, supprimer

GET    /api/servers                        # liste des serveurs + état d'exécution
GET    /api/instances                      # liste des instances
POST   /api/instances                      # créer
PUT    /api/instances/reorder              # corps : { "order": [id, ...] }
GET    /api/instance/:id                   # détails (+ état d'acceptation des conditions dans agreements)
PATCH  /api/instance/:id                   # modifier les paramètres (objet clé-valeur)
DELETE /api/instance/:id                   # supprimer
POST   /api/instance/:id/rename            # corps : { "name": "..." }
  • Principaux champs de POST /api/instances : { "name", "module_name", "port"?, "preset"?, "module_settings"?, "accept_agreements"?: [id] }. En cas de succès, renvoie 201 {success, id, ...}, et si le module définit une étape d'installation, l'installation des fichiers du serveur démarre en arrière-plan (§3.5).
  • Outre le port et les paramètres du module, PATCH /api/instance/:id accepte aussi des paramètres du démon comme :
    • auto_restart, restart_on_unknown_exit : redémarrer automatiquement ou non après un crash / un arrêt inconnu
    • extra_args : arguments de lancement supplémentaires (une chaîne ou un tableau de chaînes ; null les efface)
    • memory_limit_mb : limite de mémoire (Mio, au moins 256 ; les formes "4G"/"4096M" sont acceptées ; null/0 signifie aucune limite). S'applique uniquement sous Windows.
  • Le renommage exige que le serveur soit arrêté ; un nom déjà utilisé renvoie 409 name_taken.

3.2 Démarrer / arrêter / redémarrer

POST /api/instance/:id/start
POST /api/instance/:id/stop                # corps facultatif : { "force": true }
POST /api/instance/:id/restart             # corps facultatif : { "force": true }
GET  /api/instance/:id/events              # historique des arrêts récents
GET  /api/server/:name/status              # état par nom
  • Avant le démarrage, le démon vérifie l'acceptation des conditions et exécute les vérifications du module. Des conditions non acceptées renvoient 409 agreement_required (avec agreements) ; un échec de vérification critique renvoie 409 preflight_failed.
  • L'arrêt envoie la commande d'arrêt propre du jeu, attend le délai du module (30 secondes par défaut) et tue le processus de force s'il est toujours en vie. Avec force: true, il est tué immédiatement.
  • events renvoie {events: [...]} avec le verdict de l'arrêt (user_stop, in_game_stop, crash, unknown_exit), ses éléments probants, un éventuel redémarrage automatique planifié, etc.

3.3 Console et commandes

GET  /api/instance/:id/console?since=<id>&count=<n>
POST /api/instance/:id/stdin               # corps : { "command": "say hello" }
POST /api/instance/:id/command             # corps : { "command": "<name>", "args"?: {...} }
GET  /api/instance/:id/commands            # commandes disponibles pour ce serveur
POST /api/instance/:id/rest                # jeux REST uniquement (p. ex. Palworld)
POST /api/instance/:id/rcon                # nom de compatibilité ; suit le chemin de commande ci-dessous (stdin → REST → RCON)
  • Polling de la console : la réponse est {success, lines: [{id, timestamp, source, content, level}], running, ...}. Avec since, les lignes dont l'id est supérieur ou égal à cette valeur sont renvoyées ; envoyez donc la prochaine fois le dernier id reçu + 1. Sans since, vous obtenez les count lignes les plus récentes (100 par défaut). Le démon conserve en mémoire les 10 000 dernières lignes par serveur.
  • Ordre des chemins de commande : stdin → REST → RCON. Les commandes vont d'abord à la console du serveur (stdin), et les jeux qui ne prennent en charge que REST, comme Palworld, passent par REST. RCON n'est utilisé que pour un jeu dont le module déclare supported = ["rcon"] (ni console ni API REST) ; le démon attribue alors à chaque instance son propre port et un mot de passe aléatoire, et se connecte uniquement en loopback (127.0.0.1). Sinon, /rcon est un chemin conservé uniquement de nom pour les anciens clients et envoie vers stdin. Les serveurs sans chemin de commande renvoient 409 no_command_path.
  • /stdin renvoie 409 stdin_not_supported si le module ne prend pas en charge stdin.
  • /command exécute une commande définie par le module ; si le serveur est arrêté, renvoie 409 server_not_running.

3.4 Paramètres, conditions, vérifications

POST /api/instance/:id/launch-preview      # corps : { "settings"?: {...}, "extra_args"?: "..." }
POST /api/instance/:id/agreements          # corps : { "accept": ["eula"] }
GET  /api/instance/:id/properties          # lire le fichier de configuration du jeu
PUT  /api/instance/:id/properties          # corps : { "settings": {...} }
POST /api/instance/:id/validate            # vérification du serveur
POST /api/instance/:id/diagnose            # diagnostic des logs
  • launch-preview calcule la ligne de commande de lancement sans démarrer le serveur. Exemple de réponse : {success: true, has_launch_args, command_line, program, args, extra_args, errors: [...]}. Les valeurs de mot de passe sont masquées sous la forme ***. Si le module ne déclare aucun argument de lancement, renvoie has_launch_args: false.
  • agreements enregistre l'acceptation des conditions déclarées par le module (p. ex. eula de Minecraft). Cela ne fonctionne qu'en local ; les requêtes de sources distantes (Discord, etc.) reçoivent 403 agreement_local_only. Les id non déclarés reçoivent 400 invalid_format.

3.5 Progression de l'installation et mises à jour du serveur de jeu

GET    /api/provision-progress/:name       # :name = nom de l'instance
DELETE /api/provision-progress/:name       # fermer un état de progression en échec
GET    /api/instance/:id/check-update
POST   /api/instance/:id/apply-update

Exemple de réponse de provision-progress :

{
  "active": true,
  "step": 2,
  "total": 5,
  "label": "...",
  "message": "...",
  "percent": 40,
  "done": false,
  "error": null
}

Lorsque rien n'est en cours, renvoie {"active": false}. Un état de progression réussi est effacé automatiquement au bout de 5 secondes ; un état en échec reste jusqu'à ce que vous le fermiez avec DELETE (si le serveur était en cours de création, il est alors annulé). La progression est aussi disponible sous provision.progress sur /api/events.

apply-update renvoie 409 server_running si le serveur tourne. Une sauvegarde est effectuée avant la mise à jour (pour les modules qui prennent en charge les sauvegardes).

3.6 Sauvegardes et tâches planifiées

GET    /api/instance/:id/backups                     # { success, backups: [{ name, kind, created, size }] }
POST   /api/instance/:id/backups                     # sauvegarder maintenant
DELETE /api/instance/:id/backups/:name
POST   /api/instance/:id/backups/:name/restore       # le serveur doit être arrêté
GET    /api/instance/:id/schedule
PUT    /api/instance/:id/schedule                    # corps : { "schedule": [...], "backup_keep"?: 10 }
  • kind des sauvegardes : manual, scheduled, pre-update, pre-restore. Si le module ne prend pas en charge les sauvegardes, vous obtenez 400 backup_unsupported ; s'il n'y a encore rien à sauvegarder, 400 nothing_to_back_up.
  • La restauration renvoie 409 server_running si le serveur tourne, et l'état actuel est sauvegardé en pre-restore avant la restauration.
  • La forme d'une tâche planifiée :
{ "action": "restart", "at": "05:00", "warn_minutes": [10, 5, 1], "enabled": true }

action vaut backup | restart | announce | update, et vous utilisez exactement l'un de every_minutes (toutes les N minutes) et at (chaque jour à HH:MM). announce nécessite un message, et warn_minutes ne s'applique qu'à restart et update. Les tâches invalides renvoient 400 validation_failed (avec details).


4. Modules

GET    /api/modules                        # modules installés
POST   /api/modules/refresh                # relire le dossier des modules
GET    /api/module/:name                   # métadonnées du module
GET    /api/module/:name/versions          # versions installables du serveur de jeu
GET    /api/module/:name/locales
GET    /api/modules/manifest               # catalogue des modules installables
POST   /api/modules/manifest/:id/install   # installer un module depuis le catalogue
DELETE /api/modules/:id                    # supprimer un module

Le catalogue des modules provient de la liste de versions signée, et les fichiers téléchargés ne sont installés qu'après vérification de leur hachage.


5. Extensions

GET    /api/extensions                     # liste avec état d'installation/activation
POST   /api/extensions/rescan
GET    /api/extensions/manifest            # catalogue des extensions installables
GET    /api/extensions/updates
POST   /api/extensions/:id/install
DELETE /api/extensions/:id
POST   /api/extensions/:id/enable          # exécute le hook daemon.startup de façon asynchrone
POST   /api/extensions/:id/disable

GET    /api/extensions/:id/config
PUT    /api/extensions/:id/config

GET    /api/extensions/:id/gui             # bundle GUI (JavaScript UMD)
GET    /api/extensions/:id/gui/styles      # CSS
GET    /api/extensions/:id/i18n/:locale    # ko / en / ja / ...

Les erreurs des routes d'extensions utilisent la forme {success: false, error, error_code, ...}.


6. Paramètres

GET  /api/config/gui
PUT  /api/config/gui                       # JSON partiel (fusion superficielle)
GET  /api/config/bot
PUT  /api/config/bot                       # paramètres du bot comme le préfixe et les alias (JSON partiel)
GET  /api/system/metrics                   # CPU, mémoire, disque, utilisation par serveur

Tous les paramètres utilisateur sont stockés par espace de noms dans un seul fichier config.json du dossier de données. Le démon synchronise les paramètres du bot avec le relais. Le bot Discord lui-même tourne sur le relais cloud ; le démon n'a donc pas d'API pour démarrer ou arrêter un processus de bot.


7. Mises à jour

GET  /api/updates/status                   # état actuel et versions par composant
POST /api/updates/check                    # vérifier les mises à jour maintenant
POST /api/updates/download                 # corps facultatif : { "components": [...] }
GET  /api/updates/download/progress
POST /api/updates/apply                    # corps facultatif : { "components": [...] }
POST /api/updates/launch-updater           # appliquer via l'installateur (le démon s'arrête)
GET  /api/updates/config
PUT  /api/updates/config

Les informations de mise à jour proviennent de la liste de versions signée. Les composants dont les fichiers en cours d'exécution doivent être remplacés sont signalés dans la réponse de apply comme nécessitant une application séparée ; appeler launch-updater lance l'installateur (saba-chan-installer --apply), qui arrête le démon, remplace les fichiers et ne relance que ce qui a changé. Ces routes répondent sous la forme {ok: ...}.


8. Appairage du relais cloud

Pour le flux d'appairage GUI ↔ serveur relais. Voir la page Bot Discord pour le déroulement détaillé.

POST   /api/relay/pair/initiate            # émettre un code d'appairage (transmis au relais)
GET    /api/relay/pair/:code/status        # vérifier par polling si l'appairage est terminé
GET    /api/relay/agent                    # état de l'agent relais
POST   /api/relay/agent/start
POST   /api/relay/agent/stop
DELETE /api/config/node-token              # supprimer le jeton de nœud de ce PC (arrête l'agent)

Une fois l'appairage terminé (status: "claimed"), le démon enregistre automatiquement le jeton de nœud et reconnecte l'agent relais avec le nouveau jeton. Le démon se charge de l'authentification auprès du relais ; les clients n'ont donc pas à s'en occuper.


9. Exemple d'authentification (curl)

TOKEN=$(cat "$APPDATA/saba-chan/.ipc_token")

curl -H "X-Saba-Token: $TOKEN" \
     http://127.0.0.1:57474/api/servers

curl -X POST \
     -H "X-Saba-Token: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"command":"list"}' \
     http://127.0.0.1:57474/api/instance/<instance-id>/stdin

<instance-id> est l'id de la réponse de GET /api/servers ou de GET /api/instances.


10. Compatibilité des versions

  • Cette API est classée comme IPC privée. Ce n'est pas un contrat public ; les chemins et les schémas peuvent donc changer même dans des versions mineures.
  • Si vous distribuez un client personnalisé, vérifiez la version du démon (version de GET /health) et traitez-la avec prudence.

En cas de problème, rendez-vous sur Dépannage.