REST, wie man es erwartet
Adressen unter /v1, JSON in beide Richtungen, gewöhnliche Verfahren und gewöhnliche Statuscodes. Kein eigener Dialekt, den man erst lernen müsste.
Schnittstelle für eigene Apps Was das Portal kann, kann auch Ihr Skript.
Dieselbe Schnittstelle, die die Oberfläche bedient, steht Ihnen offen: über 400 Routen, beschrieben in OpenAPI 3.1, mit einem Schlüssel statt einer Anmeldung.
API-Schlüssel gibt es ab dem Paket Premium.
Grundlagen
Keine zweite Schnittstelle für Fremde
Es gibt nicht die schnelle interne und die abgespeckte öffentliche Fassung. Das Portal ruft dieselben Routen auf wie Sie — was dort geht, geht hier.
Maschinenlesbar beschrieben
Jede Route steht in einer OpenAPI-3.1-Beschreibung, die aus dem Quelltext entsteht und deshalb nicht altert. Daraus erzeugen Sie sich einen Client in Ihrer Sprache, statt Adressen abzutippen.
Listen mit Cursor statt Seitenzahl
Listen antworten mit items, total und nextCursor. Den Cursor geben Sie beim nächsten Aufruf zurück; fehlt er, war es die letzte Seite.
Erste Aufrufe
Drei Aufrufe, die sofort etwas zurückgeben
Setzen Sie SIGNAGE_API auf die Adresse Ihrer Instanz und SIGNAGE_API_KEY auf Ihren Schlüssel. Mehr braucht es nicht.
GET/v1/playlistsDie Listen Ihrer Organisation, seitenweise. Auf Wunsch gefiltert nach Suchbegriff, Szene oder Medium.
curl -sS "$SIGNAGE_API/v1/playlists?limit=20" \
-H "Authorization: Bearer $SIGNAGE_API_KEY"GET/v1/devicesAlle Bildschirme mit ihrem Zustand. Der Filter nach Zustand beantwortet die Frage, die man wirklich stellt: Wer meldet sich gerade nicht?
curl -sS "$SIGNAGE_API/v1/devices?status=online&limit=50" \
-H "Authorization: Bearer $SIGNAGE_API_KEY"GET/v1/devices/{id}Das Gerät samt seiner Fähigkeiten, seiner letzten Selbstmeldung und der Ausgänge, an denen noch kein Bildschirm hängt.
curl -sS "$SIGNAGE_API/v1/devices/$DEVICE_ID" \
-H "Authorization: Bearer $SIGNAGE_API_KEY"200application/jsonKein Umschlag um den Umschlag: items trägt die Sache, nextCursor die nächste Seite, total die Gesamtzahl. Fehlt nextCursor, sind Sie am Ende.
{
"items": [ … ],
"nextCursor": "cGxsOjIwMjYtMDMtMTE",
"total": 42
}Schlüssel
Ein Schlüssel erbt nie mehr Rechte, als Sie selbst haben
Sie legen Schlüssel im Portal an und geben ihnen genau die Rechte, die sie brauchen. Mehr als Ihre eigenen können Sie nicht vergeben — der Versuch wird abgewiesen.
- Der Schlüssel wird genau einmal angezeigt; bei uns gespeichert wird nur sein Fingerabdruck
- Rechte werden je Schlüssel gewählt, nicht vom Konto geerbt
- Ein Ablaufdatum ist möglich, aber keine Pflicht
- Beim Wechsel gilt der alte Schlüssel noch eine einstellbare Frist weiter — Sie tauschen ihn ohne Ausfall
- Zurückziehen wirkt sofort, und alle Schlüssel Ihrer Organisation stehen an einer Stelle
Ab dem Paket Premium
Neue Schlüssel legen Organisationen ab dem Paket Premium an. Bereits ausgestellte Schlüssel bleiben gültig und lassen sich jederzeit zurückziehen — auch wenn das Paket später wechselt.
Webhooks
Nicht nachfragen — rufen lassen
Statt im Takt zu fragen, hinterlegen Sie eine Adresse und die Ereignisse, die Sie angehen. Wir stellen zu, unterschreiben die Zustellung und zeigen Ihnen, was daraus wurde.
- Ziele sind je Organisation hinterlegt und müssen über HTTPS erreichbar sein
- Jede Zustellung trägt eine Signatur (HMAC mit SHA-256) über den unveränderten Rumpf, dazu Ereignisart und eine Zustell-Kennung gegen Doppelverarbeitung
- Das Geheimnis sehen Sie einmal und tauschen es, wann Sie wollen
- Zustellungen sind einsehbar und einzeln wiederholbar; ein dauerhaft totes Ziel wird abgeschaltet, statt endlos anzuklopfen
- Namen wie composition.scene.published, scheduling.playlist.updated oder media-library.asset.ready tragen Bereich, Gegenstand und Vorgang schon in sich
Erst ausprobieren, dann automatisieren.
Sehen Sie sich in der Testphase an, was die Plattform verwaltet. Die Schnittstelle darauf kommt mit dem Paket Premium.