State API

Brainsonic Live is relying on an in-house application called Event Engine. For each digital event, an Event Engine instance is created.

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 splittersplited into a frontend application that is executed on client environnementenvironment and a backend application that runs on a server.

ThoseThis information areis 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 requestrequest. 
• getState allows the frontend application to request Event Engine instance state every 5s.

(1)

L'
1. The frontend application récupère/metget àthe jourState saURL configuration.from the backend application
   (2)
   
Une
2. The requêtebackend côtéapplication serveurget vers l'administrationthe Event Engine retourneinstance l'urlstate duURL
   service
   d'état
   • Carries dua lecteur.
     (3)bearer L'urltoken. duJWT serviceHS256 d'étatformat,
   du lecteur retourne les informations concernant le lecteur.

   La requete (2) est porteuse d'un

   • The token (bearer)is ausigned formatwith JWT HS256, token signé avec una secret (clefAPI d'API)key)
   et
   • Contains nean contientAPI queaccess l'ID associée(aud) àand laan clef d'API (aud) et laexpiration date d'expiration(exp)
   du token (exp).
   • TTL conseillérange de= 3030s à- 60s.60s
   • To be cached on backend for 15 minutes
     
     L'url
   du
   service
d'état
3. Every (State5 APIseconds, URL)the (requêtefrontend 3)application changepull avec l'horloge du serveurthe Event Engine toutesinstance lesstate 30
   minutes.
   • Response Elleis restecached valablefor pendant5 1seconds
   heure.
   Sur
cette

url

Exemple Eventuse Enginecase

répond

avec
1. Client unapplication cacherequest dethe 5s.State
   IlURL estto conseillébackend deapplication
la
2. If mettrethe àbackend jourapplication toutesobtained lesthe State URL more than 15 minutes ago then it need to be requested again (requêterequest 1)2).
   There avecis uneno miseneed ento maintain a state on the backend server. A 15 minutes cache suron votrerequest serveur1 deis 15 minutes.
   

   
   

   Exemple de cas d'usage

   enough.
   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