Skip to main content

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 information about an Event Engine instance configuration and state.

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

This information is 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 to request Event Engine instance state every 5s.
  1. The frontend application get the State URL from the backend application

  2. The backend application get the Event Engine instance state URL
    • Carries a bearer token. JWT HS256 format,
    • The token is signed with a secret (API key)
    • Contains an API access ID (aud) and an expiration date (exp)
    • TTL range = 30s - 60s
    • To be cached on backend for 15 minutes
  3. Every 5 seconds, the frontend application pull the Event Engine instance state
    • Response is cached for 5 seconds

Exemple use case

  1. ClientFrontend application request the State URL to backend application (request 1)
  2. If the backend application obtained the State URL more than 15 minutes ago then it need to be requested again (request 2).
    There is no need to maintain a state on the backend server. A 15 minutes cache on request 1 is enough.
  3. L'Frontend application clienteuses demandethe saState configurationURL contenantto l'url de requêtage d'état (requête 1)
  4. 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.   
  5. L'application utilise l'url d'APIpull Event Engine instance state and configuration every 5 seconds (requêterequest 3) pour récupérer l'état du site en pull période >= 5s
  6. L'Frontend application clienterequests redemandea l'urlnew deState requêtageURL d'étatto (requêtethe 1)backend touteapplication lesevery ~15min15 minutes.


get State API URL

propriétés

Success de la réponse en cas de succès 

response
  • stateUrl {string} urlURL duthat serviceneed d'étatto àbe appelerrequested enby GETfrontend application

requete Method GET

requete Header bearer:<JWT>

reponse Cache: no-cache

response Status

Statuses
  • Success 200
  • Erreur Unauthorized Status 401
  • autre erreurError Status 400
Properties

LeThe token portécarried parby lathe requêterequest estis una Json Web Token encodé(JWT) avecencrypted unwith secreta partagéshared entresecret. Secret is shared between Event Engine etand lethe serveurthird departy l'backend application

  • alg: HS256
  • aud: <your site/application name>
  • exp: 3030s ouor 60s


get Sate API

propriétés

Success de la réponse en cas de succès

response
  • 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
Response statuses
  • Success 200
  • Erreur Unauthorized Status 401
  • autre erreurError Status 400


Limitations

get State API URL 

  • fréquenceHit/s maximum= 1 appel par seconde
  • quotaHit/minute = 4 appels maximum par minute

  

Back to top