API Platforms
Dokumentierte, versionierte Schnittstellen. Das Fundament, auf dem der Rest Ihres digitalen Ökosystems aufsetzt.
Risiken, die wir früh erkennen.
Was in Systemen dieser Art typischerweise schiefgeht — und wie wir es vermeiden, bevor es in Produktion sichtbar wird.
- 01
Stiller Breaking Change
- Warum
- Ein umbenanntes Feld oder eine nachträglich verschärfte Validierung wirkt wie eine Korrektur. Für den fremden Code am anderen Ende ist es ein Bruch — unabhängig davon, wie klein die Änderung wirkt.
- Frühwarnzeichen
- Änderungen am Bestand statt additiver Erweiterungen; kein automatischer Test gegen den öffentlichen Vertrag; Aufrufer melden den Fehler vor dem eigenen Monitoring.
- Wie wir es verhindern
- Additiv erweitern, wo es geht. Der öffentliche Vertrag wird automatisch getestet, bevor ausgerollt wird; wird eine neue Version nötig, bleibt die alte unberührt gültig.
- Trade-off
- Kosten: Contract-Tests und Zurückhaltung beim Ändern des Bestands. Anders, wenn: die Schnittstelle rein intern ist und mit ihren Aufrufern zusammen ausgerollt wird — dann ist der Vertrag günstig zu ändern.
- 02
Fehler ohne Vertrag
- Warum
- Fehler sind Teil des Vertrags, nicht ein Randfall daneben. Wechselnder Fließtext zwingt Aufrufer, auf Formulierungen zu prüfen — und macht die Meldung selbst zum Vertrag.
- Frühwarnzeichen
- Kein stabiler, klassifizierter Code; Client- und Serverfehler nicht unterscheidbar, sodass niemand weiß, ob wiederholt oder korrigiert werden muss; interne Details in Meldungen.
- Wie wir es verhindern
- Stabile, maschinell auswertbare Fehlercodes, eine klare Trennung zwischen Fehler des Aufrufers und Fehler des Anbieters, und keine internen Spuren in der Antwort.
- Trade-off
- Kosten: eine weitere Vertragsfläche, die mit derselben Vorsicht gepflegt wird wie die Erfolgsantworten. Anders, wenn: eine interne Schnittstelle mit einem einzigen, mitwachsenden Nutzer — dort darf das Fehlermodell schlanker bleiben.
- 03
Schnittstelle mit der Implementierung verwechselt
- Warum
- Der Anbieter hinter einer Schnittstelle ist austauschbar; die Daten, die durch sie geflossen und geblieben sind, sind es nicht. Wer die eigene Sicht an die Form eines Anbieters bindet, spürt jeden Wechsel bis in den Bestand.
- Frühwarnzeichen
- Das eigene Datenmodell folgt der Struktur eines externen Dienstes; ein Anbieterwechsel wird als Anschlussfrage geplant, nicht als Übersetzung des Bestands.
- Wie wir es verhindern
- Die Daten liegen in einer Form, die dem System gehört; der externe Dienst hängt hinter einer Grenze, die hält.
- Trade-off
- Kosten: eine Übersetzungsschicht und ein geprüft migrierter Bestand statt eines direkten Umschaltens. Anders, wenn: der Bestand klein und unkritisch ist und seine erneute Beschaffung billig wäre.
Die Fragen, die wir vor dem Code stellen.
Keine Ratschläge, sondern Entscheidungsfragen. Ihre Antworten prägen die Architektur — nicht die Werkzeuge.
- 01
Welche Form hat die Kommunikation — Dinge, Aktionen oder flexible Abfragen?
- Warum das zählt
- Der Stil prägt den Vertrag, und der Vertrag ist schwer zu ändern. Nach Mode zu entscheiden führt eine Passungsfrage als Geschmacksfrage.
- Typische Konsequenz
- Benannte Dinge führen zu REST, Aktionen zwischen bekannten Systemen zu RPC, sehr verschiedene Datenschnitte vieler Aufrufer zu GraphQL. Im Zweifel der verbreitetste Stil, den man in zehn Jahren noch versteht und besetzen kann.
- 02
Drückt die Schnittstelle die Fachlichkeit des Aufrufers aus — oder die interne Umsetzung?
- Warum das zählt
- Was ein Nutzer beobachtet, wird zum Vertrag. Gespiegelte interne Strukturen koppeln fremde Systeme an Entscheidungen, die man frei ändern können wollte.
- Typische Konsequenz
- Wir entwerfen die äußere Repräsentation getrennt vom internen Modell und übersetzen an der Grenze. Bei einem Prototyp mit kurzer Lebensdauer entfällt das.
- 03
Ändert eine Operation Zustand oder Geld?
- Warum das zählt
- Sobald eine API über ein Netz erreichbar ist, kommt dieselbe Anfrage irgendwann doppelt an. Das ist kein Fehler, sondern eine Eigenschaft verteilter Kommunikation.
- Typische Konsequenz
- Dann wird sie idempotent entworfen: ein eindeutiger Schlüssel pro logischer Operation, geprüft und persistiert in derselben Transaktion wie die Wirkung. Lesevorgänge und natürlich idempotente Operationen brauchen das nicht.
- 04
Kann ein bestehender Aufrufer die geplante Änderung bemerken?
- Warum das zählt
- Ist die Antwort ja, ist die Änderung brechend — unabhängig davon, wie klein sie wirkt. Auch eine nachträglich verschärfte Validierung ist ein Bruch.
- Typische Konsequenz
- Wir lösen sie additiv, wo es geht. Wo nicht, entsteht eine neue Version, die alte bleibt unberührt gültig, und die Abschaltung folgt einem angekündigten Deprecation-Prozess statt einem Stichtag.
Was das ist — und was dazugehört.
Eine API-Plattform stellt die Schnittstellen bereit, über die Systeme, Partner und Anwendungen miteinander sprechen. Batunet entwirft APIs als langlebige Verträge — versioniert, dokumentiert und stabil, damit alles andere sicher darauf aufsetzen kann.
Leistungsumfang
- API-Design (REST, GraphQL)
- Versionierung ohne Brüche
- Authentifizierung und Rate Limiting
- Dokumentation und Developer Experience
- Zuverlässige Webhooks und Ereignisse
So bauen wir. Die Batunet Engineering Method.
Sieben Phasen — von der ersten Frage bis zum Betrieb nach Jahren. Kein Projektprozess, sondern die Art, wie wir denken.
- 01
FrameRahmen
Das eigentliche Problem, seine Grenzen und ein messbarer Erfolg werden definiert, bevor eine Lösung erwogen wird.
- 02
ModelModellieren
Die Domäne wird modelliert und in Kontexte geschnitten — mit einer präzisen, gemeinsamen Sprache.
- 03
DecideEntscheiden
Die tragenden Entscheidungen fallen zuerst, bewusst und dokumentiert, solange Ändern noch günstig ist.
- 04
ProveBeweisen
Ein lauffähiges Skelett beweist die Architektur auf dem riskantesten Pfad — vor der Breite.
- 05
BuildBauen
Auf dem bewiesenen Skelett entsteht das System in prüfbaren, umkehrbaren Schritten — Fortschritt wöchentlich sichtbar.
- 06
HardenHärten
Fehlerfälle, Last und Sicherheit werden geprüft, nicht angenommen. Aus „läuft“ wird „hält“.
- 07
OperateBetreiben
Wir betreiben, überwachen und entwickeln weiter — und halten das System verständlich und änderbar.
Worauf Sie sich verlassen können.
- 01
Schnittstellen, die sich weiterentwickeln, ohne zu brechen
- 02
Ein stabiles Fundament für Partner und weitere Systeme
- 03
Dokumentation, mit der andere sofort arbeiten können
Wann es passt — und wann nicht.
Die ehrliche Antwort gehört zur Beratung. Wir empfehlen den Weg, der zum Problem passt.
Passt
- Mehrere Aufrufer teilen dieselbe Geschäftslogik — Frontends, mobile Apps oder Partner. Ab dem zweiten Aufrufer ist die Schnittstelle ein Vertrag, kein Implementierungsdetail.
- Bestehende Geschäftslogik soll kontrolliert zugänglich werden, ohne fremde Systeme an das Innenleben zu koppeln.
- Ein externer Dienst soll austauschbar bleiben. Eine eigene Schnittstelle davor trennt das, was bleibt, von dem, was ersetzt wird.
- Die Schnittstelle soll über Jahre additiv wachsen, ohne die Produktion ihrer Nutzer zu brechen.
Passt nicht
- Zwei eigene Dienste, die zusammen entwickelt und zusammen ausgerollt werden. Dort ist der Vertrag günstig zu ändern — eine engere Kopplung ist vertretbar.
- Ein einziger, mitwachsender Nutzer, den man selbst koordiniert. Die volle Strenge aus Vertragsfläche, stabilen Fehlercodes und Deprecation-Prozess lohnt erst bei fremden Aufrufern.
- Ein Prototyp oder eine kurzlebige Schnittstelle. Dort ist das direkte Spiegeln interner Strukturen die schnellere und richtige Wahl; die Entkopplung lohnt erst, wenn die API lange lebt.
Fragen zu API Platforms
REST oder GraphQL?
REST für stabile, cachebare Ressourcen; GraphQL, wenn Clients sehr unterschiedliche Datenschnitte brauchen. Oft ist REST die richtige, langweilige Wahl.
Wie vermeiden Sie Breaking Changes?
Durch bewusste Versionierung, additive Änderungen und klare Verträge. Eine API ist ein Versprechen an ihre Nutzer.
Setzen Sie Ihren Engineering-Weg fort.
Verwandte Konzepte, Entscheidungen, Playbooks und Standpunkte — als zusammenhängender Pfad, nicht als Linkliste.
Technologien
Leistungen
Engineering-Entscheidungen
Playbooks
Sprechen wir über Ihr Vorhaben.
Kein Vertrieb. Ein direktes Gespräch mit der Geschäftsführung. Antwort innerhalb eines Werktags.
