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. Frontend 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 needneeds 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. Frontend application uses the State URL to pull Event Engine instance state and configuration every 5 seconds (request 3)
  4. Frontend application requests a new State URL to the backend application every 15 minutes.


get State URL

Success response
  • stateUrl {string}string URL that need to be requested by frontend application
requete Method GET
requete Header bearer:<JWT>
reponse Cache: no-cache
response Statuses
  • Success 200
  • Unauthorized Status 401
  • Error Status 400
Properties

The token carried by the request is a Json Web Token (JWT) encrypted with a shared secret. Secret is shared between Event Engine and the third party backend application

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


get Sate

Success response
  • playerState string prelive|live1|live2|postlive|: prelive | live1 | live2 | postlive | vod
  • playerManifest string urlHLS du hlsURL
  • countdown object propriétésCountdown du countdownproperties
    • visible boolean : true décompte visible ou| false décompte caché
    • end unix timestamp date: decountdown finend du décomptetime
    • serverTime unix timestamp tempsserver actuelcurrent du serveur time
requete Method GET
response Cache 5s
response Status
Response statuses
  • Success 200
  • Unauthorized Status 401
  • Error Status 400


Limitations

get State URL 

  • Hit/s = 1
  • Maximum Hit/minute = 4

  

Back to top