Skip to main content

State API

This API allows third party applications to get live information about an Event Engine instance configuration and state.

We assume that this third party application is splitter into a frontend application that is executed on client environnement and a backend application that runs on a server.

Those information are provided thanks to two requests :

  • getStateURL intends to be requested from a backend application. This returns the endpoint URL that frontend application will need to request
  • getState allows the frontend application 


(1) L'application récupère/met à jour sa configuration.
(2) Une requête côté serveur vers l'administration Event Engine retourne l'url du service d'état du lecteur.
(3) L'url du service d'état du lecteur retourne les informations concernant le lecteur.

La requete (2) est porteuse d'un token (bearer) au format JWT HS256, token signé avec un secret (clef d'API) et ne contient que l'ID associée à la clef d'API (aud) et la date d'expiration du token (exp). TTL conseillé de 30 à 60s.

L'url du service d'état (State API URL) (requête 3) change avec l'horloge du serveur Event Engine toutes les 30 minutes. Elle reste valable pendant 1 heure. Sur cette url Event Engine répond avec un cache de 5s.
Il est conseillé de la mettre à jour toutes les 15 minutes (requête 1) avec une mise en cache sur votre serveur de 15 minutes.


Exemple de cas d'usage

  1. L'application cliente demande sa configuration contenant l'url de requêtage d'état (requête 1)
  2. Si le le serveur d'application a récupéré l'url de requêtage du service d'état il y a plus de 15min alors il la récupère à nouveau (requête 2). Il n'est pas nécessaire de maintenir un état sur le serveur pour cela. Une valeur de cache de ~15min dans la réponse à (requete 1) suffit.   
  3. L'application utilise l'url d'API Event Engine (requête 3) pour récupérer l'état du site en pull période >= 5s
  4. L'application cliente redemande l'url de requêtage d'état (requête 1) toute les ~15min 


get State API URL

propriétés de la réponse en cas de succès 

  • stateUrl {string} url du service d'état à appeler en GET

requete Method GET
requete Header bearer:<JWT>
reponse Cache: no-cache

response Status

  • Success 200
  • Erreur Unauthorized Status 401
  • autre erreur Status 400

Le token porté par la requête est un Json Web Token encodé avec un secret partagé entre Event Engine et le serveur de l'application

  • alg: HS256
  • aud: <your site/application name>
  • exp: 30 ou 60s


get Sate API

propriétés de la réponse en cas de succès

  • playerState string prelive|live1|live2|postlive|vod
  • playerManifest string url du hls
  • countdown object propriétés du countdown
    • visible boolean true décompte visible ou false décompte caché
    • end unix timestamp date de fin du décompte
    • serverTime unix timestamp temps actuel du serveur 

requete Method GET
response Cache 5s
response Status

  • Success 200
  • Erreur Unauthorized Status 401
  • autre erreur Status 400


Limitations

get State API URL 

  • fréquence maximum 1 appel par seconde
  • quota 4 appels maximum par minute

  

Back to top