Die API wird vom Server unter dem Pfad /api/v1/ bereitgestellt. Wenn der Server der Anzeige unter der IP-Adresse 192.168.1.5 auf Port 4711 läuft, ist die API unter http://192.168.1.5:4711/api/v1/ erreichbar. Eine Liste der Endpunkte folgt weiter unten.

Authentifikation

Alle Endpunkte – mit ganz vereinzelten Ausnahmen – sind nur mit Authentifikation benutzbar. Dies kann über zwei verschiedene Verfahren erfolgen:

JWT

Mit einem POST-Request gegen den Endpunkt /authentication kann ein JWT erworben werden. Der Request muss folgendes Format haben:

{
  "strategy": "local",
  "email": "test@example.org",
  "password": "super-secret"
}

Die Antwort enthält ein accessToken, das bei künftigen Requests im HTTP-Header Authorization als Bearer-Token verwendet werden kann. Das Token ist ab Erhalt für 24 Stunden gültig.

API-Key

Es kann auch ein statischer API-Key verwendet werden, z. B. zur Verwendung in Mikrocontrollern oder eigenen Skripten. Der Key muss im HTTP-Header x-api-key übermittelt werden.

Erzeugt werden API-Keys in der Console unter Administration > API-Keys. Ein API-Key wird nach dem Anlegen nur einmalig angezeigt und muss sofort notiert werden. Diese Keys sind bis auf Widerruf gültig.

Endpunkte

Es folgt eine Auflistung der verschiedenen Ressourcen, die über die API verwaltet werden können. Mittelfristig soll diese Liste durch eine Open API Specification abgelöst werden.

/authentication

Abruf eines JWT

/api/v1/announcements

Die Ankündigungen

/api/v1/api-keys

API-Keys

/api/v1/content-slot-options

Optionen für einzelne Content Slots

/api/v1/content-slots

Die Content Slots von Ansichten

/api/v1/displays

Die Displays

/api/v1/incidents

Die Einsätze

/api/v1/key-requests

Anfragen von Displays nach API-Keys

/api/v1/locations

Örtlichkeiten von Einsätzen

/api/v1/users

Die Benutzer

/api/v1/views

Ansichten der Displays