Events

AirServer Events

Endpoint

GET /api/v1/events

Required roles

admin:r

Description

This endpoint supplies property change events.

You can either use long-polling or Server-Sent-Events to receive JSON-formatted objects that represent changes to the AirServer configuration.

Events that belong to the System endpoint will be identified with "system.changed".

Parameters

Query parameters

initialEventId string optional

Allows the user to provide the UUID from the latest request, so that the events will resume from that point.

You should strip all quotation marks from the ETag and only provide the UUID within.

Header parameters

If-None-Match string optional

ETag for long-polling

Response headers

ETag string

ETag for long-polling

Event schema

Schema

{
  "type": "object",
  "properties": {
    "contentType": {
      "type": "string",
      "$comment": "The MIME content type for the message body. This will be application/json"
    },
    "event": {
      "type": "string",
      "$comment": "The emitted event type, such as 'system.changed'."
    },
    "data": {
      "type": "object",
      "$comment": "This is the event data."
    }
  }
}

HTTP response status codes

Status code	Description
200	OK
304	Not Modified
401	Unauthorized

Example

Server-Sent-Events

const apiKey = "{your AirServer Connect API key or JWT token}";

// fetch the initial state of the AirServer configuration
const fetchOptions = {
  headers: {
    Authorization: "Bearer " + apiKey
  }
};
const response = await fetch("https://{your AirServer hostname}/api/v1/system", fetchOptions);

let etag = null;
{
  const match = response.headers.get("etag").match(/"(.+)"/);
  if (match) {
    etag = match[1];
  }
}

// listen for change events, and apply them to the current state of the config
const currentSystemState = await response.json();
const airServerEvents = new EventSource("https://{your AirServer hostname}/api/v1/events?initialEventId=" + etag + "&apiKey=" + apiKey);
airServerEvents.addEventListener("system.changed", (e) => {
  const delta = JSON.parse(e.data);
  const newSystemState = { ...currentSystemState, ...delta };

  currentSystemState = newSystemState;
  console.log(JSON.stringify(currentSystemState, null, 2));
});

Long Polling

const apiKey = "{your AirServer Connect API key or JWT token}";

// fetch the initial state of the AirServer configuration
const fetchOptions = {
  headers: {
    Authorization: "Bearer " + apiKey
  }
};
const response = await fetch("https://{your AirServer hostname}/api/v1/system", fetchOptions);

let etag = response.headers.get("etag");

const currentSystemState = await response.json();

// listen for change events, and apply them to the current state of the config
function pollAirServer() {
  setTimeout(async () => {
    const fetchOptions = {
      headers: {
        Authorization: "Bearer " + apiKey,
        "If-None-Match": etag
      }
    };
    const response = await fetch("https://{your AirServer hostname}/api/v1/events", fetchOptions);
    etag = response.headers.get("etag");

    // if the server responds with 304 then no event was queued before the 30 second server-side timeout
    // and we should poll the server again
    if (!response.ok) {
      if (response.status == 401) {
        // should give up
        console.error("Authentication error");
        return;
      }
      if (response.status == 304) {
        // should poll again
        pollAirServer();
        return;
      }
      console.error("Unexpected status: " + response.status);
      return;
    }

    const event = await response.json();
    console.log("recieved AirServer event:", event);

    if (event.event === "system.changed") {
      const delta = event.data;
      const newSystemState = { ...currentSystemState, ...delta };

      currentSystemState = newSystemState;
      console.log(JSON.stringify(currentSystemState, null, 2));
    }

    // should poll again
    pollAirServer();
  });
}

// or some other method to set up periodic polling
pollAirServer();