API-Schnittstellen planen: Der Weg zur wartbaren Integration

API-Schnittstellen sollten Sie planen, bevor ein Team Endpunkte programmiert oder Automatisierungen verbindet. Entscheidend ist nicht zuerst die Technologie, sondern ein eindeutiger Geschäftsprozess: Welche Information wird wann von welchem führenden System an wen übergeben, und was geschieht bei Fehlern? Wenn diese Fragen beantwortet sind, lässt sich eine Integration klein beginnen, nachvollziehbar betreiben und später verändern, ohne neue manuelle Nebenprozesse zu schaffen.

Eine Integration ist kein Datentransport ohne Folgen

Zwischen CRM, ERP, Shop, Ticketsystem, Buchhaltung oder branchenspezifischer Fachanwendung wirken viele Daten auf den ersten Blick gleich: Kundendaten, Artikel, Aufträge oder Statuswerte. Fachlich können sie jedoch etwas Unterschiedliches bedeuten. Ein Kunde im CRM kann etwa ein Vertriebskontakt sein, während im ERP erst eine abrechnungsrelevante Debitorennummer einen Kunden kennzeichnet. Eine Schnittstelle, die Felder nur nach Namen zuordnet, überträgt dann möglicherweise formal korrekte, aber operativ falsche Informationen.

Darum braucht jede Integration eine fachliche Vereinbarung. Sie beschreibt den Auslöser, die erlaubten Zustände, die Datenquelle und den Empfänger. Ebenso wichtig ist die Gegenrichtung: Nicht jeder Wert darf zurückgeschrieben werden. Ohne diese Grenze entstehen konkurrierende Datenstände, deren Korrektur später wieder in Tabellen, E-Mails und Einzelabstimmungen landet.

Zuerst den Prozess und die Datenhoheit festlegen

Die zentrale Architekturentscheidung lautet: Welches System ist für welches Datenobjekt führend? „Führend“ bedeutet, dass dort ein Wert verbindlich angelegt und geändert wird. Andere Systeme dürfen ihn lesen, übernehmen oder für ihren Zweck ergänzen, aber nicht stillschweigend überschreiben. Diese Regel kann je Datenfeld unterschiedlich sein. Beispielsweise kann das CRM Ansprechpartner pflegen, während das ERP Rechnungsadresse, Zahlungsstatus und Debitorennummer verantwortet.

• Benennen Sie den konkreten Auslöser, etwa „Auftrag freigegeben“ statt „Daten regelmäßig synchronisieren“.
• Legen Sie pro Datenobjekt und bei Bedarf pro Feld ein führendes System fest.
• Definieren Sie eine stabile Zuordnung, etwa über interne IDs oder fachliche Schlüssel, nicht allein über Namen oder E-Mail-Adressen.
• Beschreiben Sie, welche Daten zwingend benötigt werden, welche optional sind und welche nicht übertragen werden dürfen.
• Klären Sie, wer fachliche Rückfragen entscheidet und wer den technischen Betrieb verantwortet.

Eine Synchronisation in beide Richtungen ist daher kein Standardmerkmal, sondern ein bewusstes Ausnahmefall-Design. Sie kann nötig sein, wenn zwei Teams jeweils in ihrem Fachsystem arbeiten müssen. Dann braucht sie jedoch klare Konfliktregeln: Was gilt, wenn beide Seiten denselben Datensatz ändern? Ohne diese Regel ist eine einseitige Übergabe häufig robuster und leichter zu prüfen.

Den kleinsten fachlich vollständigen Ablauf wählen

Große Integrationsvorhaben scheitern selten daran, dass keine Verbindung zu einer API möglich ist. Häufig werden zu viele Objekte, Sonderfälle und Rückkanäle in den ersten Release gepackt. Sinnvoller ist ein Ablauf, der einen spürbaren manuellen Schritt ersetzt und fachlich geschlossen ist. Er muss nicht alle Varianten abdecken, sollte aber für seinen abgegrenzten Zweck zuverlässig funktionieren.

Ein plausibles Beispiel ist die Verbindung mehrerer Systeme, um doppelte Datenpflege zu verringern. Nach einer definierten Freigabe im Vertriebssystem wird ein Auftrag an das führende Auftrags- oder ERP-System übergeben. Die Integration erzeugt dort keinen beliebigen neuen Datensatz, sondern prüft zunächst die Kundenzuordnung, überträgt nur freigegebene Positionen und speichert die externe Referenz zurück. Der Status der Übergabe wird im Ursprungssystem sichtbar. Fehlt ein Pflichtfeld oder ist die Zuordnung unklar, geht der Vorgang in eine prüfbare Fehlerliste statt unbemerkt verloren zu gehen.

Nicht sinnvoll ist eine Integration, wenn der Zielprozess selbst ungeklärt ist. Wer etwa Statuswerte in drei Systemen unterschiedlich verwendet, automatisiert mit einer Schnittstelle nur die Unklarheit. Ebenso sollte eine API nicht als Ersatz für Berechtigungs-, Freigabe- oder Datenqualitätsregeln dienen. Diese Regeln gehören vor oder in den Prozess, nicht in eine Reihe schwer nachvollziehbarer Sonderfälle.

Fehlerfälle sind Teil der fachlichen Anforderung

Netzwerkprobleme, abgelaufene Zugangsdaten, ungültige Eingaben und vorübergehend nicht erreichbare Fremdsysteme gehören zum normalen Betrieb. Eine belastbare Integration muss daher nicht nur den Erfolgsfall kennen. Sie muss sichtbar machen, was fehlgeschlagen ist, ob ein erneuter Versuch sinnvoll ist und wer handeln muss. Andernfalls wird die Schnittstelle zur Black Box: Erst wenn ein Auftrag fehlt oder ein Kunde falsch zugeordnet ist, fällt der Fehler auf.

1. Erfassen Sie pro Übertragung einen nachvollziehbaren Status, Zeitstempel, Quellreferenz und eine verständliche Fehlermeldung.
2. Unterscheiden Sie technische Fehler, die erneut versucht werden können, von fachlichen Fehlern wie fehlenden Pflichtangaben.
3. Sorgen Sie dafür, dass erneute Übertragungen keinen Vorgang doppelt anlegen oder ungewollt mehrfach verändern.
4. Definieren Sie einen einfachen Klärungsweg für Fehler: zuständiges Team, fachliche Entscheidung und dokumentierte Korrektur.
5. Testen Sie reale Sonderfälle vor dem Livegang, etwa unvollständige Adressen, Stornierungen, nachträgliche Änderungen und bereits vorhandene Datensätze.

Besonders wichtig ist die Vermeidung doppelter Verarbeitung. Wenn ein aufrufendes System nach einer Zeitüberschreitung nicht weiß, ob die Gegenseite den Auftrag bereits verarbeitet hat, darf ein Wiederholungsversuch nicht automatisch einen zweiten Auftrag erzeugen. Stabile Referenzen und eine Prüfung auf bereits verarbeitete Vorgänge sind dafür wichtiger als eine rein technische Erfolgsmeldung.

Sicherheit und Betrieb von Anfang an mitplanen

Eine Schnittstelle erweitert den Kreis der Systeme, die auf Daten zugreifen. Daher sollten Zugangsdaten nicht in Quellcode, Tabellen oder E-Mail-Verläufen abgelegt werden. Berechtigungen sollten zum konkreten Zweck passen: Eine Integration, die Aufträge anlegt, braucht nicht automatisch Zugriff auf alle Kunden-, Finanz- oder Nutzerdaten. Auch personenbezogene Daten verdienen besondere Aufmerksamkeit. Übertragen werden sollte nur, was der definierte Prozess tatsächlich benötigt.

Zum Betrieb gehört zudem eine klare Frage: Was passiert, wenn sich eine externe API ändert, ein Token ausläuft oder ein Quellsystem neue Pflichtfelder einführt? Dokumentierte Schnittstellenversionen, getrennte Zugänge für Entwicklung und Produktivbetrieb sowie ein begrenztes Monitoring machen Änderungen kontrollierbarer. Bei selbst betriebenen Komponenten ist außerdem zu klären, wer Updates, Sicherungen, Zugriffsverwaltung und die Beobachtung fehlgeschlagener Jobs übernimmt. Deutsches Hosting kann zur eigenen Datenschutz- und Betriebsstrategie passen, ersetzt aber keine saubere Berechtigungs- und Datenkonzeption.

Mit dieser Entscheidungsgrundlage in die Umsetzung

Vor der Entwicklung genügt oft ein kompaktes Integrationskonzept, wenn es konkret ist. Es sollte nicht aus einer Liste möglicher Endpunkte bestehen, sondern den Geschäftsvorgang verständlich abbilden. Daraus kann ein Team Aufwand, technische Risiken und sinnvolle Ausbaustufen wesentlich besser ableiten als aus der pauschalen Anforderung, zwei Systeme zu synchronisieren.

• Welcher manuelle Arbeitsschritt oder welches Fehlerrisiko soll konkret reduziert werden?
• Welches Ereignis startet die Übertragung, und wann ist es fachlich endgültig?
• Welche Systeme und Felder sind beteiligt, und welches System ist jeweils führend?
• Wie werden Datensätze eindeutig zugeordnet und Änderungen erkannt?
• Welche Fehlerfälle sind erwartbar, wie werden sie sichtbar und wer bearbeitet sie?
• Welche Daten, Berechtigungen und Betriebsaufgaben sind für die Integration erforderlich?
• Woran entscheiden Sie nach einem begrenzten ersten Ablauf, ob eine Erweiterung sinnvoll ist?

Wenn diese Punkte offen bleiben, ist zunächst ein Prozessworkshop oder eine Datenanalyse sinnvoller als sofortige Implementierung. Wenn sie beantwortet sind, kann eine individuelle Integration, eine klar abgegrenzte Automatisierung oder eine Kombination daraus passend sein. OnLouis unterstützt Teams dabei, Geschäftsprozesse in wartbare Schnittstellenkonzepte und nachvollziehbare Software umzusetzen, ohne die Verantwortung für Daten und Betrieb aus dem Blick zu verlieren.