Die perfekte API: sechs Dinge, die uns über 50 Integrationen gelehrt haben

13. August 2026·5 min Lesezeit

Wer eine Schnittstelle baut, verbringt die wenigste Zeit mit dem eigenen Code. Die Zeit geht für die andere Seite drauf: verstehen, was die fremde API wirklich liefert, herausfinden, was nur in der Dokumentation steht, und Wege um die Stellen herum bauen, an denen sie nicht mitspielt.

Wir haben inzwischen über 50 Integrationen gebaut, überwiegend zwischen einem CRM und dem jeweiligen ERP eines Kunden. Dabei entsteht mit der Zeit eine ziemlich klare Meinung darüber, was eine gute API ausmacht. Max hat diese Liste als Abschluss seines Vortrags „Systeme verbinden, ohne den Verstand zu verlieren" gezeigt, unter anderem auf den Magdeburger Developer Days und dem TechCamp 2025. Hier ist sie, mit der Begründung dahinter.

1. Pagination

Klingt selbstverständlich, ist es nicht. Eine API ohne Blätterfunktion ist genau so lange in Ordnung, wie der Kunde wenig Daten hat. Danach läuft der Aufruf in einen Timeout, und zwar ausgerechnet bei dem Kunden, der am meisten zahlt.

Wichtig ist dabei nicht nur, dass es Pagination gibt, sondern dass sie stabil ist. Wenn sich während des Blätterns die Sortierung ändert, weil parallel Datensätze angelegt werden, überspringt man Einträge, ohne es zu merken. Das ist die unangenehmste Sorte Fehler: Es fehlt etwas, aber nichts schlägt fehl.

2. Abfrage über das letzte Änderungsdatum

Das ist der wichtigste Punkt der ganzen Liste. Eine Schnittstelle will fast immer nur eines wissen: Was hat sich seit meinem letzten Lauf geändert? Wenn die API diese Frage beantworten kann, ist die halbe Arbeit erledigt. Und ein Nebeneffekt wird gern übersehen: Neuanlagen sind darin automatisch enthalten, denn ein neuer Datensatz wurde zuletzt bei seiner Erstellung geändert. Man braucht also keine zweite Abfrage für „was ist neu".

Fehlt dieses Feld, bleiben nur schlechte Optionen. Entweder holt man jedes Mal alles ab, was mit wachsendem Datenbestand unbezahlbar wird, oder man baut eine Schattendatenbank: eine eigene Kopie des letzten bekannten Standes, gegen die man vergleicht, um Änderungen selbst zu erkennen.

Das funktioniert, und wir bauen es, wenn es sein muss. Aber es ist zusätzliche Software, die betrieben, überwacht und bezahlt werden will, nur weil auf der anderen Seite ein Zeitstempel fehlt.

Eine Einschränkung gehört dazu, und die haben wir selbst erst im Betrieb gelernt: Der Zeitstempel trägt lange, aber nicht unbegrenzt. „Alles seit gestern" ist eine Frage, deren Antwort beliebig groß werden kann, und das merkt man ausgerechnet beim größten Kunden zuerst. Ab dieser Menge ist ein Postfach die bessere Frage: nicht „was hat sich seit gestern geändert", sondern „gib mir die nächsten hundert, die ich noch nicht abgeholt habe". Dann merkt sich die Gegenseite den Stand, und wie viel zurückkommt, steht im Aufruf statt im Zufall.

Damit das trägt, muss der Abruf quittiert werden. Erst wenn der Aufrufer bestätigt, gilt ein Eintrag als abgeholt. Bricht die Verarbeitung mitten im Paket ab, verarbeitet man im schlimmsten Fall etwas doppelt, statt es zu verlieren. Überall dort, wo Belege vollständig vorliegen müssen, ist das die richtige Richtung.

3. Eine Version im Pfad

/api/v2/documents. Ein winziges Detail mit großer Wirkung, denn es macht Änderungen verhandelbar. Ohne Version im Pfad gibt es nur zwei Möglichkeiten: Entweder die API ändert sich nie, oder sie ändert sich und macht dabei still alle kaputt, die daran hängen.

Mit Version im Pfad kann eine neue Fassung neben der alten stehen, und die angebundenen Systeme ziehen nach, wenn sie so weit sind. Das ist kein Luxus für große Plattformen, das ist die Grundlage dafür, dass man überhaupt weiterentwickeln kann.

4. Klar definierte Limits

Praktisch jede Plattform begrenzt, wie viele Anfragen in einem Zeitraum erlaubt sind. Das ist völlig in Ordnung und richtig so. Das Problem ist nicht das Limit, sondern das unbekannte Limit.

Steht es in der Dokumentation, planen wir es ein: Anfragen drosseln, Aufrufe bündeln, bei Ablehnung mit wachsendem Abstand erneut versuchen. Steht es nicht darin, findet man es im Betrieb heraus, meistens am Tag der ersten großen Datenmenge. Rate-Limits gehören zu den zuverlässigsten Quellen für unangenehme Überraschungen, die wir kennen.

5. Keine statische Dokumentation

Eine Dokumentation, die von Hand gepflegt wird, ist ab dem zweiten Sprint falsch. Nicht, weil niemand Lust hat, sondern weil sie an einer anderen Stelle liegt als der Code und deshalb systematisch vergessen wird. Und eine falsche Dokumentation ist schlimmer als gar keine, denn man verlässt sich darauf.

Gut ist, was aus dem laufenden System kommt und deshalb nicht veralten kann. Wir haben das für unseren eigenen Teil einer Integration gelöst: bridgelist erzeugt die Übersicht, welches Feld von wo nach wo läuft, direkt aus dem Mapping-Code. Bei jeder Integration, die wir bauen, ist sie dabei.

6. Möglichst wenige Aufrufe bis zum Ziel

Eine API, bei der man erst eine Liste holt, dann pro Eintrag die Details, dann pro Detail die Verknüpfungen, ist theoretisch sauber und praktisch unbrauchbar. Aus 500 Datensätzen werden schnell ein paar tausend Aufrufe, und Punkt 4 dieser Liste schlägt zurück.

Die Frage an jeden Endpunkt lautet deshalb: Wie viele Aufrufe braucht der häufigste Anwendungsfall? Wenn die Antwort größer als eins ist, lohnt sich ein zweiter Blick.

Und wenn die API nicht so ist?

Dann bauen wir trotzdem. Genau das ist der Job, und keine der über 50 Schnittstellen hatte auf der Gegenseite eine perfekte API. Aber es erklärt, warum eine Integration selten „schnell mal eben" geht.

Unsere gelernte Schätzung für eine einfache Schnittstelle sind 40 Stunden. Ein guter Teil davon geht für genau die sechs Punkte oben drauf, beziehungsweise für deren Abwesenheit. Wer eine API baut, an der andere andocken sollen, kann mit dieser Liste viel Zeit verschenken oder viel Zeit sparen. Es ist dieselbe Liste.

Mehr dazu, wie wir Systeme verbinden, steht auf unserer Seite zur API- und Schnittstellen-Entwicklung.

#API#Schnittstellen#Integration
Fragen zum Artikel

Es wird Zeit, bessere Software zu bauen.

Lass uns in einem kostenfreien Vorgespräch herausfinden, was der erste sinnvolle Schritt für Deine Software ist. Wir freuen uns auf Dich!

Architektur, die keiner mehr versteht?

Wir schauen gern drauf.