Offene Schnittstellen - wem die Daten gehören und wie man sie herausbekommt

Ein Analysesystem, das man nicht verlassen kann, ist kein Werkzeug. Es ist eine Falle.

Die Frage, wem die Daten gehören, wird bei der Beschaffung einer Zählanlage selten gestellt und in der Regel erst dann, wenn es zu spät ist: beim Wechsel des Anbieters, beim Aufbau eines Data Warehouse, bei der Anfrage des Controllings, die Zahlen bitte in das eigene Berichtssystem zu übernehmen. Dann zeigt sich, ob „wir haben eine Schnittstelle“ eine Zusage war oder ein Verkaufsargument.

Dieser Beitrag geht durch, woran man eine offene Architektur erkennt - am Ausgang und am Eingang. Er baut auf Von der Zahl zur Handlung auf, wo es um Aufrufe an Fremdsysteme ging, und auf Fahrgastzählung im ÖV, wo die Normformate des öffentlichen Verkehrs stehen.

Vier Wege hinaus

Eine offene Architektur hat nicht einen Ausgang, sondern mehrere, die voneinander unabhängig sind. Jeder beantwortet eine andere Frage:

Dazu kommt der Bericht, der von selbst kommt, und der Eingang, über den Daten hineinkommen. Beides gehört zur Frage der Offenheit, und beides wird unten beschrieben.

Eine Schnittstelle, auf die man eine Integration bauen kann

„Wir haben eine API“ heisst oft: ein einzelner Bericht als Endpunkt, ein Passwort im Klartext, kein Fehlerkatalog. Wer damit ein Data Warehouse füllen will, schreibt am Ende doch wieder einen Export von Hand.

Woran man den Unterschied erkennt, sind vier Eigenschaften, die man in jeder Ausschreibung abfragen kann:

• Die Analysefläche ist abrufbar, nicht ein Ausschnitt. Live-Belegung, historische Reihen von einer Minute bis zu einem Tag, Zonen und Verweildauer, Warteschlangen, Sensoranalysen, Fahrzeugzählung, Cluster, Kampagnen, Alarme und das Protokoll - dieselben Daten, die im Dashboard stehen.
• Ein einheitliches Antwortformat. Im Erfolgsfall Erfolg und Daten, im Fehlerfall Erfolg, Fehler und ein Code. Eine Integration hat damit genau einen Auswertungspfad.
• Stabile Fehlercodes - über 40, und stabil heisst: Ein Programm unterscheidet „Berechtigung fehlt“ von „Standort unbekannt“, ohne Fehlertexte zu lesen, die sich mit der nächsten Übersetzung ändern.
• Eine Versionsangabe auf jeder Antwort. Eine Integration merkt, wenn sich etwas ändert, statt es an falschen Zahlen zu merken.

Jede Anfrage wird gegen ein Schema geprüft, bevor sie die Datenbank erreicht. Das ist unsichtbar, solange alles richtig ist, und entscheidend, sobald ein Skript einen falschen Parameter schickt.

Ein Schlüssel kann nur, wofür er ausgestellt wurde

Der Zugang zur Schnittstelle läuft über Schlüssel, und die Frage ist nicht, ob es Schlüssel gibt, sondern was ein einzelner Schlüssel darf. Dafür gibt es sieben Bereiche, die bei der Ausstellung gesetzt und bei jedem Aufruf geprüft werden:

Ein Berichtswerkzeug bekommt damit einen Schlüssel, der lesen kann und sonst nichts. Wird er kompromittiert, lässt sich mit ihm kein Standort anlegen und keine Schwelle verändern.

Was mit einem Schlüssel passiert

Die Mechanik eines Schlüssels entscheidet, ob ein Leck ein Ereignis ist oder eine Katastrophe:

• Nur der Hash wird gespeichert. Der Schlüssel selbst ist genau einmal sichtbar, bei der Erzeugung. Danach kann ihn niemand mehr auslesen - auch der Anbieter nicht.
• Es gibt keine unsterblichen Schlüssel. Die Lebensdauer ist auf ein Jahr begrenzt, und wer beim Anlegen kein Ablaufdatum angibt, bekommt trotzdem eines.
• Rotation mit Überlappung. Beim Wechsel bleibt der alte Schlüssel 15 Minuten gültig, damit eine Integration ohne Ausfallfenster umstellen kann.
• Der Typ steht im Schlüssel. Produktiv, Test und Sensor sind am Präfix unterscheidbar - ein Testschlüssel in einer Produktivkonfiguration fällt beim Lesen auf.
• Jede Verwendung wird protokolliert, jede Ablehnung ebenso. Und jeder Schlüssel trägt ein eigenes Ratenlimit, voreingestellt 1'000 Anfragen pro Minute.

Ereignisse, die ankommen - auch wenn der Empfänger gerade nicht da ist

Abrufen ist teuer und langsam. Wer alle fünf Minuten fragt, ob ein Alarm ausgelöst wurde, erzeugt tausende leere Anfragen und erfährt es trotzdem im Schnitt zweieinhalb Minuten zu spät. Deshalb gibt es den umgekehrten Weg: Das System stellt Ereignisse zu - ausgelöste Alarme, Änderungen an Standorten, erreichte Zonenkapazität, überschrittene Warteschlangenschwellen, Sensorausfall und -rückkehr.

Hier liegt ein Unterschied zu den Aufrufen an Fremdsysteme aus Von der Zahl zur Handlung, und er ist gewollt. Ein Schaltbefehl muss jetzt ankommen oder gar nicht - eine Ampel, die eine halbe Stunde zu spät auf Rot springt, richtet Schaden an. Ein Ereignis muss sicher ankommen, auch wenn es dauert - ein Ticketsystem, das in Wartung war, soll den Alarm danach trotzdem haben.

Deshalb wird ein Ereignis, das nicht angenommen wird, nach einer Minute erneut zugestellt, dann nach fünf und 30 Minuten, nach zwei und nach 24 Stunden - sechs Versuche über rund 26 Stunden. Einzelne Zustellungen lassen sich danach von Hand erneut auslösen.

Vier Eigenschaften machen diesen Weg belastbar:

1. Signiert über Zeitstempel und Rohkörper. Jede Zustellung trägt eine HMAC-SHA256-Signatur über den Zeitpunkt und den unveränderten Inhalt, nicht über ein nachträglich formatiertes JSON. Jede stille Veränderung unterwegs ist damit erkennbar, und am Zeitstempel lässt sich eine veraltete Zustellung ablehnen, bevor der Inhalt überhaupt gelesen wird.
2. Die Zieladresse wird dreimal geprüft - bei der Registrierung, bei jeder Änderung und zum Zeitpunkt der Zustellung, jeweils mit Namensauflösung. Private Adressbereiche werden abgelehnt, Umleitungen nie verfolgt.
3. Keine doppelte Zustellung. Jede fällige Zustellung wird exklusiv übernommen, bevor sie versandt wird, und trägt eine eindeutige Kennung. Der Empfänger kann eine Zustellung, die er zweimal sieht, als dieselbe erkennen.
4. Selbstheilend. Eine Zustellung, die länger als zehn Minuten in Bearbeitung hängt, geht zurück in die Wiederholung. Ein abgestürzter Prozess kostet kein Ereignis. Und ein Endpunkt, der zehnmal in Folge scheitert, wird abgeschaltet, statt den Server des Empfängers weiter zu belasten.

Die Zustellhistorie zeigt je Endpunkt Status, Versuchszahl und den letzten Antwortcode. Und sie zeigt eine Erfolgsquote, die ehrlich ist: Solange keine Zustellung abgeschlossen ist, steht dort nichts - und nicht beschönigend 100 Prozent.

Dateien, die man in zehn Jahren noch öffnen kann

Das Controlling will die Zahlen in Excel, das Data Warehouse will eine Datei, der Prüfer will ein Format, das er in zehn Jahren noch öffnen kann. Ein Bildschirmfoto aus dem Dashboard erfüllt keine dieser drei Anforderungen.

Jede grosse Auswertung lässt sich deshalb als CSV und XLSX exportieren, Cluster- und Länderberichte als Arbeitsmappe mit mehreren Blättern. Für einige Bereiche gibt es die CSV-Datei zusätzlich direkt über die Schnittstelle, ohne Browser, aus einem Skript heraus.

Zwei Details entscheiden darüber, ob eine exportierte Datei sicher und brauchbar ist:

• Härtung gegen Formel-Injektion. Eine Zelle, die mit einem Gleichheitszeichen, Plus, Minus oder At-Zeichen beginnt, wird von einer Tabellenkalkulation als Formel ausgeführt. Stammt ihr Inhalt aus einem freien Textfeld - einer Notiz, einem Standortnamen -, kann damit beim Öffnen der Datei etwas geschehen, das niemand beabsichtigt hat. Solche Zellen werden deshalb mit einem vorangestellten Apostroph entschärft, auf jedem Exportweg.
• Umlaute, die ankommen. CSV-Dateien tragen eine UTF-8-Kennung, damit „Zürich“ in Excel nicht als Zeichensalat erscheint. XLSX-Dateien kommen mit angepassten Spaltenbreiten und sind ohne Nacharbeit lesbar.

Für Berichte, die jemand liest statt verarbeitet, erzeugt der Server echte PDF-Dateien - für Cluster, Länder, Fahrzeugflotte, Kampagnen und die Management-Zusammenfassung.

Der Bericht, der von selbst kommt

Wer jede Woche dieselbe Auswertung braucht, öffnet jede Woche dieselbe Seite - oder vergisst es. Und die Geschäftsleitung liest keine Dashboards. Sie liest, was im Postfach liegt.

Ein geplanter Bericht zur Standortleistung oder zur Demografie geht deshalb nach Zeitplan als PDF, XLSX oder CSV an eine Empfängerliste, mit Kopie, Standortauswahl und Versandhistorie. Vor der ersten Zustellung lassen sich ein Testversand und eine Musterdatei prüfen. Jeder Versand läuft durch eine Einwilligungsprüfung je Empfänger, und wer sich abmeldet, fällt aus dem Verteiler, ohne dass der Bericht für alle anderen endet.

Der Eingang ist genauso offen wie der Ausgang

Offenheit hat eine zweite Richtung, die fast nie gefragt wird: Wie kommen Daten hinein? Wenn nur der Hersteller weiss, wie ein Sensor seine Daten abliefert, kann niemand sonst ein Gateway anbinden, einen Testaufbau betreiben oder eine zweite Flotte aufschalten. Eine geschlossene Annahme ist die zweite Form der Bindung.

Der Eingang ist deshalb ebenso beschrieben wie der Ausgang: ein einziger Endpunkt je Standort, ein eigener Schlüssel je Standort, eine feste Grössengrenze je Übertragung und eine geprüfte Datenstruktur. Wie dieser Eingang doppelte Übertragungen erkennt und atomar zählt, steht in Personenzählung und Datenschutz.

Und es gibt einen zweiten Eingang, für Zählsysteme anderer Hersteller. An vielen Standorten steht schon ein Drehkreuz, eine Lichtschranke oder ein System eines Dritten. Wer dafür ein zweites Auswertungswerkzeug betreibt, vergleicht am Ende zwei Zahlen, die nie zusammenkommen. Über einen eigenen Endpunkt mit einem eigenen Schlüsselbereich gehen Zählwerte aus solchen Quellen in dieselben Minutenwerte wie die Sensordaten - und damit in dieselben Reihen, Alarme, Exporte und Vergleiche.

Dabei gilt eine Regel, die Doppelzählungen verhindert: Je Standort eine Quelle. Ein Standort, der bereits Sensordaten liefert, nimmt keine Fremdzählung zusätzlich an. Sonst zählt dieselbe Minute zweimal, und niemand merkt, welche.

Was in die Ausschreibung gehört

1. Ist die gesamte Analysefläche über eine Schnittstelle abrufbar - oder ein einzelner Bericht?
2. Gibt es ein einheitliches Antwortformat, stabile Fehlercodes und eine Versionsangabe?
3. Kann ein Schlüssel auf einzelne Rechte beschränkt werden, und läuft er von selbst ab?
4. Werden Ereignisse zugestellt, signiert und wiederholt - und wie lange?
5. Sind Exporte gegen Formel-Injektion gehärtet?
6. Ist beschrieben, wie Daten hineinkommen - und können Zählsysteme anderer Hersteller angebunden werden?

Wie wir das machen

Das ANALYSIT Counting System stellt seine Analysefläche über eine REST-Schnittstelle mit einheitlichem Antwortformat, über 40 stabilen Fehlercodes, Schemaprüfung und Versionsangabe bereit. Schlüssel werden auf sieben Bereiche beschränkt, nur als Hash gespeichert, laufen nach spätestens einem Jahr ab, rotieren mit 15 Minuten Überlappung und tragen ein eigenes Ratenlimit.

Ereignisse werden HMAC-signiert an bis zu fünf Endpunkte je Mandant zugestellt, mit Prüfung der Zieladresse, sechs Versuchen über rund 26 Stunden, erneuter Zustellung von Hand und Zustellhistorie. Jede grosse Auswertung exportiert CSV und XLSX mit Härtung gegen Formel-Injektion; Cluster-, Länder-, Flotten- und Kampagnenberichte gibt es als PDF. Geplante Berichte gehen nach Zeitplan per E-Mail.

Der Eingang für Sensordaten ist offen beschrieben, und Zählsysteme anderer Hersteller lassen sich über einen eigenen Endpunkt in dieselbe Auswertung einspeisen. Für den öffentlichen Verkehr kommen ITxPT und VDV 301 mit Prüfsumme dazu.

Wenn du wissen willst, wie eure Zahlen in euer eigenes System kommen, sprich mit uns. Die Antwort sollte ein Schlüssel sein, nicht ein Projekt.