API-Integration: Worauf bei Drittsystemen achten

Eine API-Integration verbindet Ihre Software mit einem fremden System. Mit der Buchhaltung, mit dem Zahlungsanbieter, mit dem Warenwirtschaftssystem. Auf dem Papier wirkt das oft trivial. In der Praxis entscheidet sich an wenigen technischen Details, ob die Anbindung jahrelang läuft oder im ersten Monat Probleme macht.

Dieser Artikel zeigt, worauf bei einer API-Integration zu achten ist. Ohne Entwickler-Jargon, aber konkret genug, um die richtigen Fragen zu stellen.

Was ist eine API überhaupt?

API steht für "Application Programming Interface". Eine Schnittstelle, über die zwei Programme miteinander reden. Mehr dazu im Glossar: API.

In der Praxis begegnen Sie drei Spielarten.

REST-APIs. Der heutige Standard. Daten werden über HTTP-Anfragen ausgetauscht. Einfach, weit verbreitet, gut dokumentiert.

GraphQL-APIs. Der Aufrufer entscheidet, welche Daten er bekommt. Flexibel, aber komplexer in der Anbindung.

Webhooks. Das fremde System ruft Ihr System aktiv an, wenn etwas passiert. Etwa: "Eine Zahlung ist eingegangen."

Welche Variante sinnvoll ist, hängt vom Anbieter ab. Sie haben dort meist keine Wahl.

Authentifizierung: Wer darf was?

Jede ernstzunehmende API verlangt, dass Sie sich ausweisen. Die gängigen Verfahren sind API-Keys, OAuth 2.0 und JWT-Tokens.

Ein API-Key ist eine lange Zeichenkette, die wie ein Passwort behandelt werden muss. Niemals im Code hinterlegen. Niemals ins Git-Repository committen. Niemals per E-Mail verschicken.

Stattdessen gehören Schlüssel in eine Konfigurationsschicht, die getrennt vom Code lebt. Umgebungsvariablen, Secret-Manager oder Vault-Lösungen. Wer das einmal sauber aufsetzt, spart sich später viele Sorgen.

OAuth 2.0 ist komplexer, aber sicherer. Statt eines Dauerschlüssels werden kurzlebige Tokens vergeben, die regelmäßig erneuert werden. Bei sensiblen Daten ist das der bessere Weg.

Versionierung: Was passiert, wenn der Anbieter etwas ändert?

APIs entwickeln sich weiter. Felder werden umbenannt, Endpunkte werden ersetzt, Verhalten ändert sich. Ein guter Anbieter versioniert seine Schnittstelle. In der URL steht dann etwa /v2/customers statt nur /customers.

Prüfen Sie vor der Integration: Wie geht der Anbieter mit Versionswechseln um? Wie lange werden alte Versionen unterstützt? Wie wird über Änderungen kommuniziert?

Ein Anbieter, der keine Versionierung anbietet, ist ein Risiko. Jede Änderung kann Ihre Integration über Nacht zerstören.

Halten Sie die genutzte Version explizit fest. Im Code, in der Dokumentation, im Wartungsplan. So wissen Sie bei einem späteren Update genau, was angepasst werden muss.

Rate-Limits: Wie oft dürfen Sie fragen?

Fast jede API begrenzt die Anzahl der Anfragen pro Zeitfenster. Etwa: 1.000 Anfragen pro Stunde. Wer das überschreitet, bekommt Fehler zurück oder wird vorübergehend gesperrt.

Vor der Integration sollten Sie wissen: Welche Limits gelten? Was passiert bei Überschreitung? Lassen sich höhere Limits beantragen?

In der Anwendung gehören dazu zwei Mechanismen.

Drosselung. Die eigenen Anfragen werden auf das erlaubte Tempo verteilt. Nicht alle auf einmal abfeuern.

Cache. Daten, die selten ändern, werden lokal vorgehalten und nicht bei jeder Anfrage neu geholt. Das schont das Limit und beschleunigt die eigene Anwendung.

Bei Diensten, die nach Anfragen abrechnen, sparen diese Maßnahmen auch Geld.

Fehlerbehandlung: Was tun, wenn die API nicht antwortet?

Das ist der Punkt, an dem die meisten Integrationen schlecht gebaut sind. Im Glücksfall läuft alles. Im Realfall kommt es zu Zeitüberschreitungen, Netzwerkproblemen oder Wartungsfenstern beim Anbieter.

Eine robuste Integration kennt diese Fälle.

Zeitüberschreitungen. Jede Anfrage braucht ein Timeout. Sonst hängt Ihre Anwendung im schlimmsten Fall ewig.

Wiederholungen. Bei vorübergehenden Fehlern wird die Anfrage ein- oder zweimal wiederholt, mit Pause dazwischen. Aber nicht endlos.

Fallback. Wenn die API gar nicht antwortet: Was passiert dann? Wird der Vorgang abgebrochen? In eine Warteschlange gelegt? Mit einem Standardwert weitergearbeitet?

Protokollierung. Jeder Fehler gehört ins Log, mit genug Kontext, um ihn später nachvollziehen zu können. Sonst suchen Sie wochenlang nach einem Problem, das schon dreimal aufgetreten ist.

Vertragsstabilität: Was ist zugesichert?

Ein zentraler Punkt, der oft unterschätzt wird. Eine API ist immer auch ein Vertrag zwischen zwei Parteien. Wer haftet, wenn sie ausfällt? Welche Verfügbarkeit ist zugesichert?

Prüfen Sie die Geschäftsbedingungen des Anbieters. Gibt es ein Service-Level-Agreement (SLA)? Was passiert bei längeren Ausfällen? Wie lange im Voraus werden Änderungen angekündigt?

Bei geschäftskritischen Integrationen ist ein Anbieter mit klaren Zusagen wichtiger als ein günstiger Preis. Eine ausgefallene Zahlungs-API bedeutet ausgefallene Umsätze.

Webhooks: Wenn das fremde System Sie anruft

Webhooks sind das Gegenstück zur klassischen API-Anfrage. Statt dass Sie fragen, ruft der Anbieter Sie an, sobald ein Ereignis eintritt.

Das ist effizient, hat aber eigene Herausforderungen.

Erreichbarkeit. Ihr Endpunkt muss aus dem Internet erreichbar sein. Mit HTTPS, mit gültigem Zertifikat.

Authentizität. Wie stellen Sie sicher, dass die Anfrage wirklich vom Anbieter kommt und nicht von einem Angreifer? Über Signaturen, die mit jedem Webhook mitgeliefert werden.

Idempotenz. Webhooks können doppelt eintreffen. Ihre Verarbeitung muss damit umgehen. Wer einen Zahlungseingang zweimal verbucht, hat ein Problem.

Antwortzeit. Anbieter erwarten meist eine schnelle Bestätigung, oft binnen weniger Sekunden. Aufwändige Verarbeitung gehört in eine Warteschlange, nicht in die direkte Antwort.

Monitoring: Wie merken Sie, dass etwas schiefläuft?

Eine Integration, die niemand beobachtet, ist eine tickende Uhr. Sie funktioniert, bis sie es nicht mehr tut. Und dann oft tagelang unbemerkt.

Sinnvolle Maßnahmen:

• Fehlerquote der API-Aufrufe als Kennzahl erfassen.
• Bei plötzlichen Ausschlägen automatisch alarmieren.
• Antwortzeiten beobachten. Schleichende Verlangsamung deutet auf Probleme hin.
• Nutzung der Rate-Limits beobachten. Wer regelmäßig nahe am Limit fährt, sollte umstellen.

Ohne Monitoring merken Sie Ausfälle erst, wenn Kunden sich beschweren. Das ist zu spät.

Häufige Fehler in der Praxis

Aus unserer Arbeit sehen wir immer wieder dieselben Probleme.

Hardcodierte Zugangsdaten im Quellcode. Ein klassischer Anfängerfehler, der erstaunlich oft auch in professionellen Projekten auftaucht.

Keine Versionierung dokumentiert. Niemand weiß, welche Version genutzt wird. Beim nächsten Anbieter-Update geht etwas kaputt.

Synchrone Verarbeitung von Webhooks. Wird die Datenbank langsam, blockiert das den ganzen Webhook-Endpunkt. Anbieter wiederholen die Zustellung, das System läuft voll.

Keine Wiederholungslogik. Ein einzelner Netzwerkfehler führt zu fehlenden Daten. Diese fehlen dann dauerhaft.

Logs ohne Kontext. "Fehler bei API-Aufruf" hilft niemandem. Welche Anfrage? Welche Antwort? Welche Zeit?

Die meisten dieser Fehler entstehen nicht aus Unwissen, sondern aus Zeitdruck. Eine gründliche Anbindung dauert länger als ein schneller Prototyp. Aber sie hält länger.

Was eine gute API-Integration auszeichnet

Wenn alles richtig läuft, merkt niemand etwas. Das ist das Ziel. Eine gute Integration ist robust gegen vorübergehende Ausfälle, klar dokumentiert, gut beobachtbar und auf Änderungen vorbereitet.

Wir bauen API-Integrationen so, dass sie nicht nur am ersten Tag funktionieren, sondern auch nach drei Jahren noch wartbar sind. Mehr zu unserem Vorgehen finden Sie unter Weiterentwicklung.

Fazit

Eine API-Integration ist mehr als ein paar Zeilen Code. Sie ist eine technische Beziehung zu einem fremden System, mit allem, was eine Beziehung ausmacht: klare Regeln, gutes Krisenmanagement, regelmäßige Pflege.

Wer die Anbindung sorgfältig plant, hat jahrelang Ruhe. Wer sie hastig zusammensteckt, baut Wartungsaufwand auf, der sich später zinst.

Wenn Sie eine API-Integration planen oder eine bestehende prüfen lassen wollen, sprechen Sie uns an. Das Erstgespräch ist kostenlos. Jetzt Kontakt aufnehmen.