Pilotage via l’API HTTP

Tout ce que fait l’interface web, le nœud sait le faire sur une requête venue de l’extérieur : l’API HTTP lit et modifie la configuration du service en fonctionnement et restitue son état. Avec l’interface web, ce sont les seules interfaces qui appliquent une modification immédiatement et en rendent compte.

Cette page donne la vue d’ensemble : où se trouve l’API, comment elle est organisée, comment arrivent les erreurs et en quoi elle diffère de la modification du fichier de configuration. La référence des requêtes et des clés figure dans des documents distincts (Documents de référence) ; elle n’est pas reprise ici.

Accès

L’API répond sur le même serveur web que l’interface d’administration. Dans la configuration livrée, il s’agit du port 8808 ; si aucun port n’est indiqué dans les paramètres, le service utilise la valeur intégrée 43971. Le port TLS est 43981, mais juste après l’installation TLS est désactivé et ce port n’est pas écouté (Réglages initiaux). L’API n’a ni adresse ni préfixe propre du type /api.

• HTTP et HTTPS sont sur un pied d’égalité. La redirection du port ouvert vers TLS ne concerne que les pages de l’interface ; les requêtes API continuent de fonctionner sur les deux protocoles.

• L’authentification est HTTP Digest, avec les mêmes comptes que l’interface web et les mêmes rôles : Admin — accès complet, Restricted admin — tout lire et mettre en pause un flux, son entrée ou sa sortie, Viewer — lecture seule. Une écriture effectuée hors de son rôle est refusée. À la place d’un mot de passe, la session peut être présentée par une clé d’ouverture automatique — cookie, en-tête X-Auth-Token ou paramètre ?auth-token=.

• Les requêtes venues du nœud lui-même ne sont pas authentifiées. Un appel arrivé par l’interface de bouclage (127.0.0.1, ::1) passe sans Digest et reçoit le rôle Admin. Cela ne peut pas être désactivé : il n’existe aucun réglage pour le faire. Cette tolérance a toutefois des bornes : elle ne peut pas être réclamée depuis l’extérieur du nœud — se donner une adresse de bouclage au moyen d’un en-tête ne fonctionne pas — et elle est retirée pour une requête cross-origin, faute de quoi une page web ouverte sur le nœud commanderait toute l’API via 127.0.0.1 sans le moindre identifiant.

  Une seule conséquence appelle une action : tout processus sur le nœud dispose de la configuration sans mot de passe. Si un proxy inverse est placé devant l’API, dirigez-le vers une adresse non bouclée du même nœud — l’authentification fonctionne alors normalement. Un proxy qui s’adresse à 127.0.0.1 distribue un accès complet à tous ceux dont il relaie les requêtes.

• Il n’y a que deux méthodes — GET et POST. Toute autre méthode reçoit la réponse « méthode non prise en charge » ; l’exception est la requête préalable OPTIONS du navigateur, à laquelle le serveur répond par une autorisation si l’origine de la requête est admise.

Avertissement

Le rôle ne restreint que l’écriture. Le contrôle du rôle s’applique aux requêtes POST ; la lecture n’est restreinte par rien, et les valeurs sont renvoyées telles quelles, sans masquage. Un compte doté du rôle Viewer voit tous les mots de passe, les secrets Meshwork, les phrases secrètes des transports et les clés de protection du contenu — et l’export d’une copie de sauvegarde des paramètres est lui aussi une lecture, soit la configuration entière en une requête. Le rôle Viewer limite la possibilité de modifier le nœud, non l’accès à ses secrets : créez-le en le sachant.

La diffusion des flux et du guide des programmes fonctionne sur ses propres ports et ne gère pas les paramètres (Réglages initiaux).

De quoi se compose l’API

Famille	Rôle
/config/…	Lecture et modification de la configuration. L’arbre des requêtes reprend pour l’essentiel la structure du fichier de configuration : une section du fichier est un nœud de l’arbre (Structure du document). Il y a des écarts : le tableau des stockages d’archive s’adresse par /config/dvr-storage et les jeux de chaînes du guide des programmes par /config/epg-channel-set, alors que dans le fichier ils se trouvent à l’intérieur de dvr-storage-list et de epg-server.
/data/…	L’état du service en fonctionnement, principalement en lecture : les flux et leurs chaînes de traitement, le matériel, le guide des programmes, le moniteur système, le journal, les informations de licence. Quelques requêtes modifient l’état — remise à zéro des statistiques, lancement d’un balayage, acquittement d’une alerte ; une seule d’entre elles modifie la configuration — le retrait d’un pair Meshwork de l’aperçu du domaine. Des exemples de requêtes tout prêts figurent dans Programme quotidien en JSON et Assistant de réclamation.
/schema/…	Listes de référence au format JSON, en lecture seule : les types d’entrée et de sortie pris en charge par ce build, les langues, les cartes de réception et les périphériques de transcodage détectés, l’échelle de gravité et les codes d’alarme. Elles n’ont aucun rapport avec le fichier de schéma des paramètres (Vérification avec le JSON Schema).
Adresses isolées	Quelques requêtes de service hors de ces arbres : redémarrage du service, export et restauration d’une copie de sauvegarde des paramètres, liste des interfaces réseau, fin de la session.

Comment arrivent les erreurs

Une erreur de niveau applicatif est renvoyée par l’API avec le code HTTP 200 et un champ result non nul dans le corps de la réponse : valeur hors plage, contrôle refusé, tentative d’écrire une clé immuable, refus d’écrire une clé inaccessible à ce rôle.

Un script qui ne vérifie que le code HTTP tiendra donc pour des succès tous ces refus les uns après les autres. Analysez le corps de la réponse.

Des codes autres que 200 se rencontrent aussi, mais ils signifient autre chose : 401 — l’authentification n’a pas abouti, 403 — le rôle n’est pas admis à la requête elle-même, 404 — cette requête n’existe pas, 405 — la méthode n’est pas prise en charge. Un refus lié au rôle arrive donc de deux manières différentes : la requête entière est rejetée par le code 403, tandis qu’une clé isolée non admise revient dans une réponse ordinaire avec un result non nul.

Une valeur hors de la plage autorisée, l’API la refuse. C’est en cela qu’elle diffère de la lecture du fichier de configuration, où une telle valeur est ramenée à la borne de la plage (Accepté, mais pas comme l’auteur de la modification l’entendait).

Une clé inconnue, l’API ne la refuse pas : elle est ignorée exactement comme à la lecture du fichier, la réponse arrive avec result 0, et la seule trace reste dans le journal du nœud. Une faute de frappe dans un nom de clé est donc invisible ici aussi — les noms de clés se vérifient à l’avance avec le schéma (Vérification avec le JSON Schema).

Modifications qui exigent un redémarrage

Deux modifications ne prennent effet qu’après un redémarrage du service : l’activation de la licence et la restauration des réglages depuis une sauvegarde. Ni l’une ni l’autre ne laisse le redémarrage à l’appréciation de l’opérateur : une fois le fichier accepté, le service se redémarre lui-même au bout d’environ quatre secondes — cela ne peut pas être différé, et le nœud est indisponible pendant le redémarrage. Les réponses à ces deux requêtes ne portent pas de champ reboot ; dans les réponses JSON de l’API de configuration, il signifie que le nœud part déjà en redémarrage, et non qu’un redémarrage attend une commande. De la même façon, de lui-même, redémarre le nœud dont la licence a expiré. Redémarrer le service de son propre chef est possible par une requête distincte, depuis l’interface web ou avec la commande sudo systemctl restart pss.

Le changement des ports d’écoute et l’activation de TLS n’exigent pas de redémarrer le service : il ferme la socket d’écoute et la rouvre, et le champ reboot sera absent de la réponse. Les connexions ouvertes sur ce port sont rompues à cette occasion, et il faut ensuite se connecter sur le nouveau port.

API ou fichier de configuration

	HTTP API	Le fichier pss.json
Quand cela prend effet	Immédiatement	Au prochain démarrage du service
État du service	En fonctionnement	Arrêté
Résultat	Renvoyé dans la réponse	Visible seulement dans le journal après le démarrage
Valeur hors plage	Refusée	Ramenée à la borne
Clé inconnue	Ignorée silencieusement, result 0	Ignorée silencieusement, sauf à lire le journal
À quoi cela convient	Modifications ponctuelles, automatisation, observation	Modifications en masse, transport des paramètres entre nœuds et versions

Modifier le fichier d’un service en fonctionnement est inutile et dangereux : le service réécrit pss.json à partir de ce qu’il garde en mémoire, et le fait selon son propre calendrier — la modification disparaîtra sans le moindre message. Arrêtez le service et vérifiez le fichier avec le schéma avant de le démarrer ; la marche à suivre est Modifier, vérifier et transporter les paramètres.

Documents de référence

Document	Contenu
http_config_api.txt	La référence de l’API de configuration : le protocole, les opérations, l’arbre /config et la description article par article de chaque clé — type, contraintes, valeur par défaut.
http_data_api.txt	La référence de l’API d’état et de statistiques : l’arbre /data, les formats de réponse, les requêtes au journal et aux bases.
pss_config_file.txt	La référence du format du fichier de configuration. Son exposé pour l’opérateur est Le fichier de configuration pss.json.
pss_config_editing.txt	Les procédures de modification, de vérification et de transport des paramètres. Leur exposé est Modifier, vérifier et transporter les paramètres.
pss.schema.json, pss.compat.schema.json	Une description lisible par machine du fichier de configuration au format JSON Schema (Vérification avec le JSON Schema).

Les documents sont rédigés en anglais. Ils ne font pas partie du paquet : ils ne sont pas sur le nœud et il est inutile de les y chercher.

Tout cela est publié sur le site de la documentation, avec un répertoire par version du produit :

https://doc2.pstreamer.tv/reference/      quatre documents de référence
https://doc2.pstreamer.tv/schema/         deux schémas

Prenez le répertoire de la version que vous avez installée : la référence d’une autre édition ne décrit pas votre nœud.

Avertissement

La compatibilité ascendante n’est pas garantie. Une mise à jour peut modifier aussi bien l’API HTTP que le schéma et le format du fichier de configuration : la composition et les noms des clés, les plages de valeurs, la forme des requêtes et des réponses. Revérifiez les scripts qui travaillent avec l’API après chaque mise à jour, et prenez les documents de référence et le schéma de la même version que le build installé.

Il en découle trois règles pour qui écrit sa propre intégration :

• Attachez-vous à la version pour laquelle le script est écrit, et vérifiez-la au démarrage.

• Relisez après avoir écrit. Une clé qui n’existe plus dans le nouveau build n’est pas refusée mais ignorée, et la réponse annonce pourtant un succès : la seule requête qui aurait attrapé cette disparition ne l’attrape pas.

• Un attribut absent de la réponse signifie « cette version ne le communique pas », et non zéro. Sinon, un indicateur supprimé ou renommé lors d’une mise à jour se transforme en une mesure vraisemblable de quelque chose qui n’existe pas.