APIs und Schnittstellen

Schnittstellen werden fast immer unterschätzt. Der größte Teil des Aufwands liegt in den Fragen, die vorher niemand gestellt hat: Was passiert, wenn das andere System nicht antwortet? Wer gewinnt, wenn beide Seiten denselben Datensatz geändert haben? Wie merkt jemand, dass seit zwei Tagen nichts mehr ankommt?

Fünf Fragen vor der ersten Zeile Code

Bevor ich eine Schnittstelle baue, klären wir vier Punkte. Wer ruft wen auf und in welcher Frequenz. Welche Seite hält die führende Version eines Datensatzes. Was geschieht bei einem Ausfall der Gegenstelle. Wie erfährt ein Mensch davon, dass seit Stunden nichts mehr übertragen wurde. Die Antworten bestimmen die Bauform stärker als jede Stildebatte über REST. Eine Übertragung, die nachts einmal läuft und den Bestand neu schreibt, sieht anders aus als eine, die auf jede einzelne Änderung sofort reagiert.

Eine API, mit der andere Entwickler arbeiten können

REST-APIs baue ich mit Versionierung im Pfad, damit Ihre Abnehmer nicht bei jeder Änderung mitziehen müssen. Die Authentifizierung läuft über Tokens mit begrenztem Umfang, sodass ein angebundenes Partnersystem nur die Endpunkte erreicht, die es tatsächlich braucht. Jede Antwort hat eine feste Struktur, auch im Fehlerfall, mit einem maschinenlesbaren Fehlercode neben dem Text für Menschen. Dazu gehört eine OpenAPI-Beschreibung, die aus dem Code erzeugt wird und deshalb nicht veraltet, während die Implementierung weiterläuft. Ratenbegrenzung und Idempotenz-Schlüssel für schreibende Aufrufe kommen dazu, sobald Bestellungen oder Zahlungen im Spiel sind. Ohne Idempotenz erzeugt ein wiederholter Aufruf nach einem Timeout die zweite Bestellung.

Systeme, die gar keine Schnittstelle mitbringen

Ältere Anwendungen haben oft keine API. Manchmal existiert eine SOAP-Schnittstelle aus den 2000ern, manchmal nur eine Datenbank und ein Verzeichnis, in das nachts CSV-Dateien abgelegt werden. Auch damit lässt sich arbeiten. Ich lege dann eine eigene Schicht davor, die nach außen eine saubere Schnittstelle anbietet und intern das tut, was das Altsystem verlangt. Der Nutzen zeigt sich später: Wird das Altsystem irgendwann ersetzt, ändert sich für die angebundenen Systeme nichts. Direktzugriffe fremder Anwendungen auf Ihre Datenbank vermeide ich aus demselben Grund. Sie machen jede Tabellenänderung zu einem Abstimmungstermin mit Dritten. Liegen die Daten in einer Oracle-Datenbank, gilt das genauso: Die Anbindung übernimmt die Zwischenschicht, nach außen sieht niemand, welches System dahintersteht.

Der Umgang mit Störungen ist der eigentliche Aufwand

Der größere Teil der Arbeit an einer Schnittstelle steckt darin, was bei Fehlern passiert. Fehlgeschlagene Aufrufe wiederhole ich mit wachsendem Abstand, damit eine kurzzeitig überlastete Gegenstelle nicht zusätzlich unter Druck gerät. Was auch nach mehreren Versuchen scheitert, landet in der Warteschlange für fehlgeschlagene Jobs und geht nicht verloren. Und es gibt eine Stelle, an der ein Mensch sehen kann, wann zuletzt erfolgreich übertragen wurde. Stille Schnittstellen sind die teuersten. Ihr Fehler fällt erst auf, wenn jemand bereits mit falschen Zahlen weitergearbeitet hat.