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. Client application request the State URL to backend application
  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'application cliente demande sa configuration contenant 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'API Event Engine (requête 3) pour récupérer l'état du site en pull période >= 5s
  6. 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