API REST Vajra Cast : Automatisez votre infrastructure de streaming

Pourquoi une API REST ?

Une interface web est idéale pour les opérations manuelles — créer une route, vérifier la santé d’un flux, ajuster les paramètres pendant un événement en direct. Mais l’infrastructure de streaming moderne exige l’automatisation. Vous devez créer des routes dynamiquement, les intégrer à des systèmes de planification, déclencher des basculements depuis des moniteurs externes et gérer des centaines de flux sans cliquer dans des menus.

Vajra Cast expose une API REST complète qui couvre chaque opération disponible dans l’interface web. Si vous pouvez le faire dans l’interface, vous pouvez le faire avec une requête HTTP.

Bases de l’API

URL de base

L’API est servie sur le même port que l’interface web :

http://votre-serveur:8080/api/v1

Tous les endpoints sont préfixés avec /api/v1. HTTPS est recommandé pour les déploiements en production — placez Vajra Cast derrière un reverse proxy (Nginx, Caddy, Traefik) avec terminaison TLS.

Authentification

Les requêtes API nécessitent une clé API transmise dans l’en-tête Authorization :

Authorization: Bearer votre-cle-api-ici

Les clés API sont générées dans l’interface web de Vajra Cast sous Paramètres > Clés API. Vous pouvez créer plusieurs clés avec des permissions différentes pour différents points d’intégration.

Format de réponse

Toutes les réponses sont en JSON. Les requêtes réussies retournent HTTP 200 (ou 201 pour la création) avec les données de la ressource. Les erreurs retournent les codes HTTP appropriés avec un corps d’erreur JSON :

{
  "error": "not_found",
  "message": "La route avec l'ID 42 n'existe pas"
}

Endpoints principaux

Routes

Les routes sont l’unité fondamentale dans Vajra Cast. Une route connecte une ou plusieurs entrées à une ou plusieurs sorties, avec transcodage et basculement optionnels.

Lister toutes les routes :

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes

Créer une route :

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Principale",
    "enabled": true
  }' \
  http://localhost:8080/api/v1/routes

Obtenir une route spécifique (avec statut complet) :

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes/1

Supprimer une route :

curl -X DELETE -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes/1

Entrées

Les entrées (ingests) sont attachées aux routes. Chaque route peut avoir plusieurs entrées pour le basculement.

Ajouter une entrée SRT listener à une route :

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "srt-listener",
    "port": 9000,
    "latency": 200,
    "passphrase": "MaPhraseDePasseSecurisee2026",
    "pbkeylen": 32,
    "priority": 1
  }' \
  http://localhost:8080/api/v1/routes/1/inputs

Ajouter une entrée RTMP en secours :

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "rtmp-listener",
    "port": 1935,
    "streamKey": "flux-secours",
    "priority": 2
  }' \
  http://localhost:8080/api/v1/routes/1/inputs

Sorties

Les sorties définissent où le flux est dirigé. Plusieurs sorties par route sont prises en charge (distribution zéro-copie).

Ajouter une sortie SRT push :

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "srt-caller",
    "host": "cdn-ingest.example.com",
    "port": 9000,
    "latency": 500,
    "passphrase": "PhraseDePasseCDN2026"
  }' \
  http://localhost:8080/api/v1/routes/1/outputs

Ajouter une sortie RTMP push (par exemple, YouTube Live) :

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "rtmp-push",
    "url": "rtmp://a.rtmp.youtube.com/live2",
    "streamKey": "votre-cle-youtube"
  }' \
  http://localhost:8080/api/v1/routes/1/outputs

Statut et métriques

Obtenir le statut en temps réel d’une route :

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes/1/status

Retourne l’entrée active, l’état de santé par entrée, l’état de connexion par sortie, le débit courant, la perte de paquets et l’état de basculement.

Obtenir la santé globale du système :

curl http://localhost:8080/api/health

Pas d’authentification requise. Retourne HTTP 200 si l’application fonctionne et que la base de données est connectée.

Schémas d’intégration

Automatisation d’événements planifiés

Pour les diffuseurs avec un programme (offices religieux, événements sportifs, émissions récurrentes), l’API permet une automatisation complète :

# 30 minutes avant l'événement : créer la route et les entrées
curl -X POST ... /api/v1/routes
curl -X POST ... /api/v1/routes/1/inputs
curl -X POST ... /api/v1/routes/1/outputs

# Fin de l'événement : démontage
curl -X DELETE ... /api/v1/routes/1

Intégrez cela avec cron, un système de planification ou votre plateforme d’automatisation broadcast.

Infrastructure as Code

Définissez votre infrastructure de streaming dans des scripts versionnés. Au déploiement, les scripts créent toutes les routes, entrées et sorties via l’API. Si vous devez reconstruire le système, relancez les scripts.

Cela fonctionne bien avec Terraform ou Ansible :

# deploy-streams.sh
for route in $(cat routes.json | jq -c '.[]'); do
  curl -X POST -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "$route" \
    http://localhost:8080/api/v1/routes
done

Déclencheurs de basculement externes

Votre système de supervision existant (Nagios, Zabbix, Datadog) peut déclencher des actions de basculement via l’API quand il détecte des problèmes que la supervision intégrée de Vajra Cast pourrait ne pas repérer (par exemple, des problèmes au niveau du contenu comme un mauvais angle de caméra, un audio dans la mauvaise langue) :

# Forcer le basculement vers l'entrée de secours
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activeInput": 2}' \
  http://localhost:8080/api/v1/routes/1/failover

Notifications par webhook

Vajra Cast peut envoyer des notifications par webhook pour les événements clés (commutations de basculement, changements d’état de connexion, erreurs). Configurez les webhooks via l’API :

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/votre-webhook",
    "events": ["failover", "disconnect", "reconnect"]
  }' \
  http://localhost:8080/api/v1/webhooks

Cela permet les alertes Slack, l’intégration PagerDuty ou tout workflow de notification personnalisé.

Limitation de débit et bonnes pratiques

L’API n’impose pas de limitation de débit par défaut, mais suivez ces bonnes pratiques :

• Interrogez les endpoints de statut pas plus d’une fois par seconde. Pour les métriques en temps réel, utilisez le endpoint Prometheus plutôt que d’interroger l’API REST.
• Utilisez le endpoint Prometheus pour la supervision. Le endpoint /metrics est conçu pour le scraping à haute fréquence et est plus efficace que les endpoints de statut REST.
• Mettez en cache les listes de routes. Les configurations de routes changent rarement. Mettez la liste en cache et invalidez-la lors des opérations de création/suppression.
• Utilisez des noms de route explicites. Les noms apparaissent dans les logs, les métriques et les alertes. Production-Principale-2026-03-07 est mieux que route1.

Gestion des erreurs

Codes d’erreur courants et leur signification :

Prochaines étapes

• Retournez au Guide de routage des flux en direct pour l’architecture complète de routage
• Découvrez les métriques en temps réel pour la supervision avec Prometheus et Grafana
• Explorez le déploiement Docker et Kubernetes pour l’automatisation d’infrastructure