API-Schnittstelle planen: Systeme zuverlässig verbinden

Ihr Vertrieb erfasst einen Auftrag in einer Anwendung. Die Disposition soll anschließend einen Arbeitsvorgang in einem anderen System erhalten. Beide Anbieter nennen eine API. Damit ist noch offen, ob die benötigten Daten gelesen und geschrieben werden können, ob Ihr Tarif diese Nutzung erlaubt und wie ein fehlgeschlagener Vorgang behandelt wird.

API steht für Application Programming Interface, eine definierte Schnittstelle zwischen Anwendungen. Bei einer HTTP-API sendet eine Anwendung eine Anfrage an einen vorgesehenen Endpunkt und erhält eine Antwort. Das kann ein Datensatz, eine Bestätigung oder eine Fehlermeldung sein. Eine Integration verbindet diese technischen Möglichkeiten mit Ihren betrieblichen Regeln.

Formulieren Sie deshalb ein vollständiges Ziel: „Freigegebene Aufträge aus System A sollen in System B einen Arbeitsvorgang mit Auftragsnummer, Termin und zuständigem Team erzeugen.“ Ergänzen Sie, wer die Freigabe erteilt und welche Fälle ausdrücklich nicht übertragen werden. Ein solches Ziel lässt sich prüfen; „die Systeme sollen miteinander sprechen“ bleibt zu unbestimmt.

Notieren Sie auch den heute nötigen Handgriff. Wird ein Datensatz abgeschrieben, eine Datei hochgeladen oder eine Information telefonisch ergänzt? Die Verbindung soll diesen Ablauf an einer konkreten Stelle verbessern. Eine API kann geeignete Übertragungen ermöglichen, löst jedoch keine ungeklärte Freigabe oder widersprüchliche Stammdatenverwaltung.

Eine Feldzuordnung, häufig Mapping genannt, beschreibt den Weg vom Quellfeld zum Zielfeld. Schreiben Sie nicht nur „Datum nach Datum“. Ist es das Erfassungsdatum, der gewünschte Termin oder der tatsächliche Abschluss? Welche Zeitzone gilt? Bedeutet ein leeres Feld „unbekannt“, „löschen“ oder „nicht verändern“? Diese Entscheidungen beeinflussen das Ergebnis stärker als die Wahl einer Programmiersprache.

Bestimmen Sie außerdem die maßgebliche Quelle für jede Information. Das Auftragssystem kann für die Auftragsnummer zuständig sein, während die Disposition den Einsatztermin verwaltet. Eine pauschale Synchronisierung in beide Richtungen kann diese Zuständigkeit verdecken. Beginnen Sie mit einem klaren Übertragungsweg und ergänzen Sie Rückmeldungen nur dort, wo sie fachlich gebraucht werden.

Identifizieren Sie Datensätze über stabile Kennungen, die zwischen den Systemen nachvollziehbar zugeordnet sind. Ein Name kann sich ändern und mehrfach vorkommen. Wenn ein Quellsystem dieselbe Person oder denselben Auftrag unter einer neuen Kennung liefert, braucht die Anbindung eine ausdrücklich vereinbarte Behandlung. Eine automatische Zusammenführung anhand ähnlicher Namen ist keine verlässliche allgemeine Regel.

Halten Sie Übersetzungen von Statuswerten ebenfalls fest. „Freigegeben“ in System A darf beispielsweise erst zu „bereit zur Planung“ in System B werden, wenn die vereinbarten Pflichtangaben vorliegen. Unbekannte Statuswerte sollen sichtbar behandelt werden. Eine stillschweigende Standardzuordnung könnte einen neuen fachlichen Zustand irrtümlich wie einen bekannten übernehmen.

Eine Anfrage kann beim Ziel bereits einen Auftrag angelegt haben, obwohl die Antwort unterwegs verloren geht. Eine sofortige Wiederholung könnte dann einen zweiten Auftrag erzeugen. Legen Sie deshalb fest, wie eine bereits ausgeführte Operation erkannt und wie ein unklarer Zustand überprüft wird. Das ist besonders bei schreibenden Verbindungen wichtig.

RFC 9110 zu HTTP unterscheidet unter anderem idempotente Methoden: Die beabsichtigte Wirkung identischer Wiederholungen entspricht dabei der Wirkung einer einzelnen Anfrage. Daraus lässt sich keine pauschale Zusage für jeden betrieblichen API-Ablauf ableiten. Für das konkrete Anlegen und Ändern gelten die Regeln des Endpunkts und der Anwendung.

Als Anbieterbeispiel beschreibt Stripe Idempotenzschlüssel für bestimmte API-Anfragen. Ein solcher Mechanismus kann Wiederholungen zuordnen. Ob Ihr Zielsystem etwas Vergleichbares unterstützt, muss gesondert geprüft werden. Falls nicht, braucht die Integration einen geeigneten eigenen Zuordnungs- und Abgleichweg.

Auch Nutzungsgrenzen beeinflussen den Ablauf. Die GitHub-Hinweise zu Rate Limits zeigen beispielhaft, dass Grenzen vom Zugriff und Endpunkt abhängen können. Vereinbaren Sie für Ihre Verbindung begrenzte Wiederholungen, Wartezeiten nach Anbieterhinweisen und eine erkennbare Meldung an zuständige Personen. Ein endloser Wiederholungsversuch kann die Störung verschärfen.

Erfassen Sie für die Diagnose eine Vorgangskennung, Zeitpunkt, betroffene Operation und verständlichen Fehlerstatus. Vollständige Nutzdaten und Zugangsdaten gehören nicht pauschal ins Protokoll. Die Meldung muss erkennen lassen, ob etwas abgelehnt, noch nicht versucht oder möglicherweise bereits verarbeitet wurde. Diese Zustände benötigen unterschiedliche nächste Schritte.

Grenzen Sie den ersten Auftrag auf benötigte Daten und einen nachvollziehbaren Ablauf ein. Jede zusätzliche Richtung, Statusänderung oder Löschregel erweitert die Anforderungen. Eine gut begründete Grenze spart keine notwendige Prüfung aus; sie macht das erste Ergebnis konkret und beherrschbar. Die Auswahl zwischen zeitgesteuerter Abfrage und Ereignismeldung behandelt der Artikel Webhooks oder Polling.

Die Übergabe sollte den veröffentlichten Codestand, Konfiguration ohne Secrets, Feldzuordnung, Testfälle und den Umgang mit Störungen beschreiben. Klären Sie, wer Anbieteränderungen verfolgt und wer bei widerrufenem Zugriff handeln kann. Ein späterer API-Versionswechsel kann eine neue Prüfung erfordern, auch wenn sich die sichtbare Oberfläche nicht verändert.

Wenn ein Anbieter keine geeignete API bereitstellt, kann ein erlaubter Dateiweg sinnvoll sein. Dafür gelten eigene Format-, Prüf- und Wiederholungsregeln, die CSV-Import und Export planen erläutert. Eine automatisierte Bedienung fremder Oberflächen sollte nicht ohne Prüfung der erlaubten Nutzung als gleichwertiger Ersatz zugesagt werden.

Ruhrstack beschreibt unter Entwicklung von Schnittstellen und individuellen Funktionen die Prüfung von Dokumentation, Datenformaten, Zugriffsrechten und Fehlerverhalten vor der Umsetzung. Für die erste Einordnung helfen die beteiligten Systeme und ein anonymisiertes Beispiel des heutigen Ablaufs. Daraus lässt sich klären, welche Voraussetzungen geprüft und welche Funktion konkret entwickelt werden sollen.