API

Tout ce que fait l’interface web passe par l’API : un script peut en faire autant. L’API est servie par heron-api derrière heron-web, à http://<hôte>:8000/api/v1.

La référence

Le document OpenAPI est généré depuis le code et servi par chaque station :

http://<hôte>:8000/api/v1/openapi.json

Il décrit chaque route et chaque type. Cette page en donne une vue d’ensemble.

Principes

• Requêtes et réponses sont en JSON.
• Les dates sont en temps Unix en millisecondes (*_unix_ms), les durées en millisecondes (*_ms).
• Les erreurs prennent la forme {"error": "<code>", "message": "…"}, avec des codes comme unauthorized (401), forbidden (403), not_found (404), conflict (409), invalid (422) et engine_unavailable (503).

Authentification

Jetons d’API, pour les scripts

Créez un jeton depuis Compte dans l’interface web (ou POST /api/v1/tokens). Il n’est affiché qu’une fois. Envoyez-le comme jeton bearer :

curl -H 'Authorization: Bearer heron_…' http://localhost:8000/api/v1/player

Un jeton agit au nom de son utilisateur, avec son rôle. Les jetons peuvent expirer et être révoqués.

Sessions

POST /api/v1/auth/login avec {"username", "password"} pose un cookie de session. Les requêtes qui modifient quelque chose avec un cookie doivent aussi envoyer un en-tête X-Requested-With (n’importe quelle valeur) :

api=http://localhost:8000/api/v1
curl -c cookies -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "…"}' $api/auth/login
curl -b cookies $api/player
curl -b cookies -X POST -H 'X-Requested-With: curl' $api/player/skip

Après 5 échecs de connexion, un nom d’utilisateur est bloqué une minute.

Sans connexion

GET /api/v1/status, /api/v1/library/status et /api/v1/openapi.json ne demandent pas de connexion.

Principales routes

Domaine	Exemples
Lecteur	GET /player, POST /player/skip, /player/pause, /player/resume, POST /player/fx
File d’attente	GET /queue, POST /queue ({"track_ids", "position"}), DELETE /queue/{entry_id}, PUT /queue/{entry_id}/position
Bibliothèque	GET /tracks (recherche, filtres, tri), GET /tracks/{id}, GET /tracks/{id}/waveform
Zone tampon	GET /staging, envois, POST /staging/import
Rotation	/clocks, /schedule, /restrictions, GET /rotation/picks, POST /rotation/simulate
Historique	GET /history
Réglages	/settings/playout, /settings/rotation, /settings/station, /settings/library…
Sorties	/encoder-profiles, /outputs (administrateurs)
Utilisateurs	/users (administrateurs), /tokens

Ce qui modifie des fichiers (imports, tags, rangement, suppression) passe par une tâche de bibliothèque : la route répond 202 avec la tâche, et GET /library/tasks/{id} indique quand elle est done ou failed.

WebSocket en direct

/api/v1/live diffuse l’état de la station. Chaque message a un type :

type	Quand
state	À la connexion, puis à chaque changement des platines, de la file, des sorties ou de la joignabilité du moteur
positions	Deux fois par seconde : la position de chaque platine
levels	Dix fois par seconde, sauf si l’URL contient ?levels=false
track	À chaque changement de piste, started ou ended

Rôles

Rôle	Peut
viewer	Tout lire, sauf les utilisateurs et les secrets
operator	Aussi faire tourner la station : file, transport, FX, programmation, simulations
admin	Aussi les réglages de diffusion, d’analyse, de bibliothèque et de station, les sorties et les utilisateurs

Les secrets (mots de passe des sorties, clé AcoustID) ne sont jamais renvoyés, à personne.

Gérer les utilisateurs en ligne de commande

docker compose exec heron-api heron-api user add <nom> --role operator
docker compose exec heron-api heron-api user passwd <nom>
docker compose exec heron-api heron-api user list