API Schnittstelle Entwicklung: Systeme verbinden, ohne dass Daten auseinanderlaufen

Ein Montagmorgen in einem Betrieb mit drei Systemen: Im Auftragsprogramm steht ein Kunde mit der neuen Lieferadresse, in der Buchhaltung noch mit der alten, und im Webshop gibt es ihn zweimal, weil er sich einmal mit einer anderen Mailadresse registriert hat. Niemand hat einen Fehler gemacht. Jedes System war für sich richtig, und gerade das ist das Problem.

In diesem Szenario nehmen wir einen mittelgroßen Dienstleister an, der über Jahre Fachsoftware zugekauft hat. Jedes Programm hat eine Exportfunktion, ein paar haben eine API, eines liefert nur CSV-Dateien per Mail. Zwischen den Systemen arbeitet eine Person, die Dateien öffnet, Spalten verschiebt und Werte kopiert. Das funktioniert, solange diese Person da ist und die Spaltenreihenfolge gleich bleibt.

Wer eine Schnittstelle entwickeln lässt, kauft deshalb keine Verbindung, sondern ein Verhalten: Was passiert, wenn derselbe Auftrag zweimal ankommt, wenn das Zielsystem gerade nicht antwortet oder wenn jemand ein Feld umbenennt? Die Antworten auf diese Fragen bestimmen, ob die Integration trägt. Dass zwei Programme Daten austauschen können, ist die leichte Hälfte der Aufgabe.

Hinzu kommt, dass der Handaustausch Wissen verbirgt. Die Person zwischen den Systemen weiß, dass bestimmte Kunden nie automatisch angelegt werden dürfen, dass eine Spalte manchmal Kommentare statt Zahlen enthält und dass der Export am Monatsende länger dauert. Dieses Erfahrungswissen steht in keiner Dokumentation. Wer es beim Automatisieren nicht erfragt, baut eine Schnittstelle, die genau diese Sonderfälle falsch behandelt.

Die meisten Schnittstellenprobleme sehen anfangs wie Zufall aus. Ein Auftrag fehlt im Zielsystem, ein anderer ist doppelt vorhanden, ein Zugriff schlägt montags fehl und dienstags nicht. Hinter diesen Erscheinungen stecken wenige wiederkehrende Ursachen, und sie lassen sich benennen, bevor man die erste Zeile Code schreibt.

Die erste ist Zeit. Zugangsdaten laufen ab, Tokens werden erneuert, Zertifikate verlieren ihre Gültigkeit. Die zweite ist Menge: Fremdsysteme begrenzen Abfragen pro Minute und antworten bei Überschreitung typischerweise mit dem Statuscode 429. Die dritte ist Bedeutung: Das Feld „Status“ heißt in beiden Systemen gleich, kennt aber unterschiedliche Werte. Die vierte ist Veränderung, denn der Anbieter der Fremd-API aktualisiert seine Software, ohne Ihren Wartungsplan zu kennen.

Hinzu kommt, dass Netzwerke unzuverlässig sind. Ein Aufruf kann beim Empfänger ankommen, verarbeitet werden, und die Bestätigung geht unterwegs verloren. Der Absender sieht einen Timeout und wiederholt. Ohne Vorkehrung entsteht dadurch genau der doppelte Auftrag, den niemand erklären kann. Dieses Muster ist keine Ausnahme, sondern ein Normalfall verteilter Systeme.

Eine fünfte Ursache wird oft unterschätzt: die stille Teilübertragung. Ein Abgleich verarbeitet 400 von 500 Datensätzen, bricht bei einem fehlerhaften Eintrag ab und meldet nichts, weil der Prozess formal beendet wurde. Am nächsten Tag fehlen 100 Datensätze, und niemand weiß, welche. Ob eine Integration Einzelfehler isoliert oder den ganzen Lauf abbricht, ist deshalb eine bewusste Entwurfsentscheidung.

Bevor über REST oder Webhooks gesprochen wird, steht eine Frage der Zuständigkeit: Welches System ist für welches Datum die führende Quelle? Wenn Kundenadressen sowohl im Auftragsprogramm als auch in der Buchhaltung bearbeitet werden dürfen, ist jede Synchronisation ein Streit, den ein Algorithmus nicht entscheiden kann. Mit klarer Datenhoheit wird aus einem Zweiwegeabgleich meist ein Einwegefluss mit definierten Ausnahmen.

Die zweite Analyse betrifft den Auslöser. Soll das Zielsystem sofort wissen, was passiert ist, oder genügt ein Abgleich alle paar Stunden? Sofort heißt: Webhooks oder Ereignisse. Regelmäßig heißt: Abfrage nach Änderungszeitpunkt. Beides hat Kosten. Webhooks liefern schnell, kommen aber auch mal gar nicht, doppelt oder in falscher Reihenfolge an. Abfragen sind träge, aber leichter zu reparieren, weil man jederzeit nachfragen kann, was seit gestern geändert wurde.

Drittens sieht man sich die Schnittstellenform des Fremdsystems an. Eine gut dokumentierte REST-API mit Sandbox ist die komfortable Lage. Häufiger gibt es eine halbfertige API, die nicht alle Felder abbildet, oder nur einen Dateiimport per CSV oder XML. Dann ist die Dateischnittstelle keine Notlösung, sondern ein Format, das man mit Prüfsummen, festen Dateinamen und Quittungsdateien robust machen kann.

Zuletzt gehört die Frage nach dem Schaden in die Analyse: Was kostet es, wenn eine Übertragung eine Stunde, einen Tag oder eine Woche ausfällt? Ein verspäteter Newsletter-Kontakt ist verschmerzbar, eine fehlende Freigabe für eine Lieferung nicht. Aus der Antwort folgt, wie viel Aufwand für Überwachung und Wiederanlauf gerechtfertigt ist.

Der verlockende Weg ist die Punkt-zu-Punkt-Verbindung: System A ruft direkt System B auf. Bei zwei Systemen ist das vertretbar. Bei fünf Systemen entstehen bis zu zehn Verbindungen, die jeweils eigene Formate, eigene Fehlerbehandlung und eigene Zugangsdaten haben. Jede Änderung an einem System betrifft mehrere Stellen. Wir würden deshalb ab dem dritten angebundenen System eine zentrale Integrationsschicht vorschlagen.

Diese Schicht ist unspektakulär: ein kleiner Dienst, der Daten entgegennimmt, in ein internes Modell übersetzt, in einer Warteschlange ablegt und an die Zielsysteme verteilt. Sie sammelt an einer Stelle Zugangsdaten, Protokolle und Wiederholungslogik. Der Preis ist ein zusätzlicher Baustein, den jemand betreiben muss. Bei zwei Systemen und stabilen Schnittstellen wäre das Overkill, und wir würden es sagen.

Eine Alternative sind fertige Integrationsplattformen und No-Code-Werkzeuge. Sie sind schnell eingerichtet und decken Standardfälle gut ab, etwa „neue Anfrage im Formular, neuer Eintrag im CRM“. Ihre Grenze liegt dort, wo Daten umgerechnet, abgeglichen oder bei Fehlern gezielt wiederholt werden sollen, und in der Abhängigkeit vom Anbieter. Für einfache Flüsse ist das eine ehrliche Option; für Prozesse, an denen Abrechnung oder Lieferung hängt, wägen wir sorgfältiger ab.

Entscheidend ist ein Gedanke: Die Integration gehört zur Software, nicht neben sie. Sie hat Versionen, Tests, Überwachung und einen Verantwortlichen. Wer sie als Nebenprodukt behandelt, bekommt ein Skript, das ein Mitarbeiter irgendwann nicht mehr zu ändern wagt.

Der zentrale Entwurfsschritt ist das Datenmodell zwischen den Systemen. Wir legen für jede Entität, etwa Kunde, Auftrag oder Artikel, fest, welche Felder es gibt, welche Pflicht sind, welche Werte erlaubt sind und welches System sie führt. Dazu gehört eine Zuordnungstabelle: Wie wird aus dem Wert „offen“ im einen System der Wert „in Bearbeitung“ im anderen? Solche Tabellen wirken banal, klären aber die Fragen, die später Wochen kosten.

Besonders wichtig ist eine stabile Kennung. Wenn zwei Systeme denselben Kunden meinen, brauchen sie einen Schlüssel, der beiden bekannt ist. Namen und Mailadressen eignen sich schlecht, weil sie sich ändern. Üblich ist, dass die Integration die Kennung des Fremdsystems neben der eigenen speichert. Fehlt so ein Schlüssel, bleibt nur ein unscharfer Abgleich über Ähnlichkeit, und der erzeugt Fehlzuordnungen, die man erst bei der Rechnung bemerkt.

Weitere Details sind unscheinbar und tückisch: Zeitzonen und Zeitstempel, Dezimaltrennzeichen, Rundung bei Beträgen, Zeichensätze bei Umlauten, leere Werte gegenüber nicht gesendeten Feldern. Ein Feld, das nicht übertragen wird, kann „unverändert“ oder „gelöscht“ bedeuten. Diese Unterscheidung muss ausdrücklich definiert sein, sonst überschreibt eine Aktualisierung vollständige Datensätze mit Lücken.

Das Modell wird als Schema beschrieben, zum Beispiel mit JSON-Schema, und jede eingehende Nachricht wird dagegen geprüft. Ungültige Nachrichten landen nicht still im Ziel, sondern in einer Liste, die ein Mensch sehen kann. So wird aus einer Datenqualitätsfrage ein sichtbarer Vorgang.

Beginnen wir mit dem Zugang. Fremd-APIs verlangen meist einen API-Schlüssel oder OAuth 2.0 mit kurzlebigen Zugriffstoken und einem Erneuerungstoken. Schlüssel liegen nie im Quelltext, sondern in einem geschützten Speicher des Servers, und sie bekommen nur die Rechte, die die Integration braucht. Läuft ein Token ab, muss der Dienst es selbst erneuern und das Ereignis protokollieren. Ein Kalendereintrag für das Auslaufen eines Zertifikats ist kein Luxus.

Bei Webhooks gilt: schnell bestätigen, später verarbeiten. Der Empfänger prüft die Signatur der Nachricht, legt sie in die Warteschlange und antwortet sofort mit Erfolg. Die eigentliche Verarbeitung läuft getrennt. So blockiert ein langsames Zielsystem nicht den Absender, und eine Nachricht geht nicht verloren, nur weil die Verarbeitung scheiterte. Weil Absender ihre Nachrichten bei Misserfolg wiederholen, muss der Empfänger Dubletten vertragen.

Hier kommt die Idempotenz ins Spiel. Eine Operation ist idempotent, wenn ihre mehrfache Ausführung dasselbe Ergebnis hat wie die einmalige. Praktisch erzeugt der Absender zu jeder Übertragung eine eindeutige Kennung, und der Empfänger merkt sich, welche er bereits verarbeitet hat. Kommt dieselbe Kennung erneut, wird sie bestätigt, aber nicht erneut ausgeführt. Manche APIs bieten dafür einen Idempotenz-Schlüssel im Kopf der Anfrage an; wo nicht, baut man die Prüfung selbst.

Bei Fehlern unterscheidet die Integration zwei Klassen. Vorübergehende Fehler wie Timeouts, Serverfehler und Statuscode 429 werden wiederholt, mit wachsendem Abstand und etwas Zufall, damit viele Wiederholungen nicht gleichzeitig eintreffen. Dauerhafte Fehler wie ungültige Daten oder fehlende Berechtigung werden nicht wiederholt, sondern zurückgestellt und gemeldet. Wer alles blind wiederholt, belastet das Fremdsystem und verdeckt die eigentliche Ursache.

Zum Schluss gibt es die Quittung: Nur wenn das Zielsystem den Erfolg bestätigt und eine eigene Kennung zurückgibt, gilt die Übertragung als abgeschlossen. Diese Kennung wird gespeichert und verbindet beide Datensätze dauerhaft.

Sonderfälle sind in Integrationsprojekten der Regelfall. Der erste ist der Nachholbetrieb: Nach einem Ausfall von einem Tag sollen die liegengebliebenen Daten übertragen werden, und die Fremd-API erlaubt nur eine begrenzte Zahl von Abfragen pro Minute. Hier hilft ein Ratenbegrenzer im eigenen Dienst, der die Aufrufe gleichmäßig verteilt, die Antwortköpfe der API auswertet und bei 429 die angegebene Wartezeit respektiert. Ein Nachholbetrieb darf den Normalbetrieb nicht verdrängen.

Der zweite Sonderfall ist die Reihenfolge. Webhooks können vertauscht eintreffen: Die Änderung „Auftrag storniert“ kommt vor „Auftrag angelegt“. Der Dienst muss entweder die Reihenfolge anhand eines Versionszählers oder Zeitstempels erkennen und ältere Nachrichten verwerfen, oder er fragt beim Eintreffen den aktuellen Stand direkt beim Absender ab. Letzteres ist robuster, aber teurer im Verbrauch an Aufrufen.

Drittens die Versionierung der Fremd-API. Seriöse Anbieter führen Versionen und kündigen das Ende alter Versionen an. Die Integration legt deshalb die verwendete Version ausdrücklich fest, statt sich auf eine Standardversion zu verlassen, und liest Hinweise zur Abkündigung aus Antwortköpfen und Änderungsmitteilungen. Wichtig ist auch Toleranz beim Lesen: Neue, unbekannte Felder in einer Antwort dürfen nicht zum Absturz führen. Fehlen dagegen Pflichtfelder, soll die Integration laut scheitern statt leise falsche Daten zu schreiben.

Viertens die Anbindung von Altsystemen, die weder API noch Webhooks haben. Ein Laborsystem oder ein älteres ERP liefert vielleicht jede Nacht eine Datei in ein Verzeichnis. Auch das lässt sich sauber lösen: Dateien werden erst verarbeitet, wenn eine Abschlussmarkierung vorliegt, jede Zeile bekommt eine Kennung, und eine Quittungsdatei zeigt zurück, was angenommen wurde. Man sollte solche Anbindungen nicht als minderwertig betrachten, sondern als langsame, aber gut prüfbare Schnittstelle.

Der Nutzen einer Integration zeigt sich dort, wo bisher Menschen als Datenbrücke gearbeitet haben. Weniger Abtippen bedeutet weniger Tippfehler, schnellere Weitergabe und frei werdende Zeit. In dieser Studie nennen wir keine Zahlen, weil sie von Ihrem Ausgangsbild abhängen: Wie viele Datensätze wandern täglich, wie oft entstehen Fehler, wie lange dauert die Korrektur? Diese Größen sollten vor dem Projekt gemessen werden, sonst fehlt später der Vergleich.

Messen lässt sich der Erfolg an wenigen Kennzahlen: Anteil erfolgreich übertragener Nachrichten, Zahl und Alter zurückgestellter Fälle, Dauer vom Ereignis bis zur Ankunft im Zielsystem, Abgleichsdifferenzen bei einer regelmäßigen Stichprobe und Nacharbeitsstunden pro Monat. Ein Dashboard mit diesen Werten ist weniger eindrucksvoll als ein Architekturbild, aber im Betrieb nützlicher.

Ebenso wichtig ist die Grenze der Zusage. Eine Integration kann nur so zuverlässig sein wie das schwächste angebundene System. Fällt die Fremd-API für einen Tag aus, wird sie das nicht ausgleichen, sondern die Daten nachholen, sobald das System zurück ist. Auch Qualitätsmängel in den Quelldaten verschwinden nicht. Eine Schnittstelle macht Fehler sichtbar und überträgt schlechte Daten schnell, wenn man sie nicht an der Quelle behebt.

Realistisch ist deshalb der Anspruch, dass Übertragungen nachvollziehbar sind, Fehler gemeldet statt verschluckt werden und ein Ausfall nicht zu Datenverlust führt. Das ist weniger als „läuft immer“, aber deutlich mehr, als viele gewachsene Skripte leisten.

Getestet wird zuerst gegen die Sandbox des Fremdanbieters, sofern es eine gibt. Sie erlaubt, Fehlerfälle gefahrlos auszulösen: ungültige Daten, abgelaufene Tokens, erreichte Limits. Wo keine Sandbox existiert, hilft ein eigener Nachbau der Fremd-API als einfacher Testdienst, der aufgezeichnete Antworten liefert. Er ersetzt den Praxistest nicht, macht aber Wiederholungslogik und Idempotenz automatisiert prüfbar. Produktive Daten gehören nicht in Tests.

Die Beobachtbarkeit im Betrieb ist ebenso wichtig wie der Code. Jede Übertragung bekommt eine Korrelationskennung, die in allen Protokolleinträgen auftaucht, sodass sich der Weg eines Datensatzes nachverfolgen lässt. Alarme sollten wenige, aber aussagekräftige Zustände melden: Zugangsdaten laufen bald ab, die Warteschlange wächst, Fälle sind länger als eine festgelegte Zeit zurückgestellt. Ein Alarm, der täglich ohne Folge ausgelöst wird, wird ignoriert.

Die Dokumentation sollte so geschrieben sein, dass eine Person ohne Vorwissen die Integration betreiben kann. Dazu gehören die Datenflüsse, das Zuordnungsmodell, der Ablauf bei Ausfall, die Verwaltung der Zugangsdaten, die Kontaktstelle beim Fremdanbieter und eine Liste bekannter Eigenheiten. Letztere sind oft der wertvollste Teil, denn sie halten fest, was nirgends in der offiziellen Dokumentation steht.

Wartung ist kein Anhang, sondern Teil des Vertrags mit sich selbst. Fremd-APIs ändern sich, Zertifikate laufen aus, Bibliotheken veralten. Ein fester Rhythmus für Abhängigkeitsupdates und eine Prüfung der Änderungsmitteilungen der Fremdanbieter kosten wenig, verglichen mit einer Notreparatur am Monatsende. Wer nur die Entwicklung beauftragt und den Betrieb ungeklärt lässt, bekommt später das Skript, das niemand anfasst.

Wer eine API Schnittstelle entwickeln lässt, sollte nicht fragen, ob die Daten ankommen, sondern was passiert, wenn sie es nicht tun. Diese Perspektive trennt belastbare Integrationen von Skripten, die im Normalfall funktionieren. Zugangsdaten, Limits, Wiederholung, Versionierung und Dokumentation sind dabei keine Zusatzleistungen, sondern der Kern der Arbeit.

Ein sinnvoller nächster Schritt ist klein. Notieren Sie für zwei Ihrer Systeme, welches bei Kunden, Aufträgen und Artikeln jeweils führt, und wo heute Menschen Daten von einem ins andere tragen. Allein diese Liste zeigt meist, welche Verbindung am meisten Nacharbeit verursacht und welche Anbindung sich zuerst lohnt. Oft ist es nicht die größte, sondern die am häufigsten fehlerhafte.

Wir schauen uns Ihre Systemlandschaft gern gemeinsam an und sagen klar, wo eine eigene Entwicklung sinnvoll ist und wo ein fertiges Werkzeug genügt. Für den ersten Fluss nennen wir einen Rahmen, nachdem wir die Fremdschnittstellen gesehen haben, nicht vorher. Zusagen ohne diesen Blick wären geraten.

Auch den Zeitpunkt der Umstellung planen wir mit Ihnen. Ein Parallelbetrieb, in dem alte und neue Übertragung für einige Wochen nebeneinander laufen und regelmäßig abgeglichen werden, kostet etwas Mühe, schafft aber Vertrauen. Erst wenn die Differenzen erklärt sind, wird die manuelle Brücke abgeschaltet, und die Person, die sie bisher getragen hat, bleibt als Kennerin der Sonderfälle eingebunden.