API-first entwickeln: Integrationen von Anfang an planbar machen

Ein Muster, das ich in Projekten immer wieder sehe: Ein Team baut eine Webanwendung, die Datenbank und die Oberfläche wachsen eng miteinander verzahnt, alles funktioniert gut – bis die erste externe Integration ansteht. Ein Partner will Bestelldaten abrufen, die mobile App soll dieselben Funktionen bekommen, oder ein KI-Agent soll Termine automatisch buchen können. Jetzt zeigt sich: Es gibt keine saubere Schnittstelle, nur interne Funktionen, die notdürftig nach außen gebogen werden. Jede neue Anbindung wird zur Sonderlösung, jede Änderung an der Oberfläche riskiert, etwas zu brechen, das ein anderes System still mitbenutzt.

Dieser Artikel gehört zu unserem Themen-Cluster KI-Softwareentwicklung und beantwortet die Kernfragen zu API-first: Was das Vorgehen bedeutet, welche Ressourcen man definiert, wie Versionierung und Authentifizierung funktionieren, wie man Schnittstellen testet und wann der Aufwand übertrieben ist. Er richtet sich an Geschäftsführung, Operations, IT und Fachbereich in KMU, die ein internes Tool, ein Kundenportal oder eine Produktintegration beauftragen oder mitentscheiden – ohne dass API-first für sie zwingend Handarbeit am Code bedeutet.

Das Problem: Integration als Nachgedanke

Software, die ohne Schnittstellenplan entsteht, funktioniert oft lange gut – solange sie ein geschlossenes System bleibt. Das Problem zeigt sich verzögert, meist genau dann, wenn das Unternehmen wächst: ein zweites Frontend, ein Partner-System, eine Automatisierung, ein KI-Agent, der Bestellungen prüfen oder Termine anlegen soll. Jede dieser Anforderungen trifft auf dieselbe Situation: Die vorhandene Logik ist tief mit der Oberfläche verwoben, es gibt keinen dokumentierten Vertrag darüber, welche Daten in welchem Format verfügbar sind, und niemand kann mit Sicherheit sagen, was passiert, wenn sich ein internes Feld ändert.

Die Folgen sind konkret und wiederkehren in ähnlicher Form:

• Jede Integration wird zum Einzelprojekt. Ohne dokumentierte Schnittstelle muss jedes neue System erst reverse-engineeren, wie die Daten intern aussehen – Zeit, die bei einer geplanten Schnittstelle nicht anfällt.
• Änderungen werden riskant. Wenn niemand weiß, wer welche interne Funktion mitbenutzt, wird jede Anpassung zur potenziellen Störung für ein System, an das man beim Ändern gar nicht gedacht hat.
• KI-Agenten und Automatisierung bleiben außen vor. Werkzeuge, die Aufgaben automatisch erledigen sollen – Bestellungen anlegen, Status abfragen, Termine buchen – brauchen eine stabile, dokumentierte Schnittstelle. Ohne die bleibt Automatisierung Stückwerk oder wird über brüchige Umwege (Screen-Scraping, manuelle Exporte) notdürftig gelöst.

API-first dreht diese Reihenfolge um: Die Schnittstelle – also der Vertrag darüber, welche Daten und Aktionen ein System nach außen anbietet – wird entworfen und mit den Beteiligten abgestimmt, bevor Oberfläche oder interne Umsetzung entstehen. Das bedeutet nicht, dass alles öffentlich oder für Dritte zugänglich sein muss. Es bedeutet, dass auch die eigene Oberfläche nur ein Konsument unter mehreren möglichen ist – und entsprechend behandelt wird.

Begriffe kurz geklärt

Vier Begriffe werden in Gesprächen häufig vermischt:

• API (Application Programming Interface) ist die Schnittstelle, über die zwei Systeme miteinander sprechen – meist per HTTP, mit definierten Ressourcen, Datenformaten (üblicherweise JSON) und Aktionen darauf.
• API-first ist ein Vorgehen, kein bestimmtes Protokoll: Die Schnittstelle wird als eigenständiges Ergebnis entworfen und abgestimmt, bevor Code entsteht – unabhängig davon, ob die Umsetzung später als REST-API, GraphQL-Schnittstelle oder anders erfolgt.
• Contract-first ist eine konkrete Umsetzung von API-first: Die Spezifikation (etwa nach dem offenen OpenAPI-Standard der OpenAPI Initiative) wird zuerst geschrieben, und Code sowie Tests werden dagegen entwickelt oder sogar teilweise daraus generiert.
• API-Gateway ist die technische Komponente, über die Zugriffe auf eine oder mehrere Schnittstellen laufen – zuständig für Authentifizierung, Ratenbegrenzung und Routing, aber kein Ersatz für einen durchdachten Schnittstellenentwurf.

Wichtig ist die Abgrenzung nach unten: Eine interne Funktion, die zufällig über HTTP erreichbar ist, ist noch keine API im hier gemeinten Sinn. Eine API im API-first-Verständnis hat einen dokumentierten Vertrag, eine bewusste Versionsstrategie und Konsumenten, die sich auf diesen Vertrag verlassen können – intern wie extern.

Was bedeutet API-first?

API-first bedeutet, die Schnittstelle eines Systems zu entwerfen, bevor die Benutzeroberfläche oder die interne Logik gebaut wird – als eigenständigen Vertrag zwischen Anbieter und Nutzer der Daten. Ressourcen, Datenformate, Fehlerfälle, Versionierung und Authentifizierung werden dokumentiert und mit Beteiligten abgestimmt, bevor der erste Code entsteht. Das Ziel ist, dass App, Partner-Integration und künftige KI-Agenten dieselbe stabile Schnittstelle nutzen können, statt dass jede Integration eine eigene Sonderlösung braucht.

In der Praxis heißt das konkret: Bevor jemand eine Bildschirmmaske entwirft, steht bereits fest, welche Ressource dahintersteckt (zum Beispiel „Bestellung”), welche Felder sie hat, welche Aktionen darauf erlaubt sind (anlegen, ändern, stornieren) und welche Fehler auftreten können (Artikel nicht verfügbar, Zahlungsdaten ungültig). Die Oberfläche wird dann als ein Konsument dieser Schnittstelle gebaut – wie jeder andere Konsument auch. Das erzwingt eine Disziplin, die sich später auszahlt: Wenn die Oberfläche etwas braucht, das die Schnittstelle nicht hergibt, fällt das beim Entwurf auf, nicht erst bei der dritten Integration.

Das ist ein Unterschied zu „API second” – dem Vorgehen, bei dem zuerst die Anwendung gebaut und die Schnittstelle im Nachhinein aus der bestehenden Logik extrahiert wird. API second ist nicht grundsätzlich falsch; für ein einzelnes, in sich geschlossenes Tool ohne absehbare Integrationsbedarfe kann es der schnellere Weg sein. Der Unterschied liegt im Risiko: Wer API second geht, verschiebt die Integrationskosten in die Zukunft, wo sie meist höher ausfallen, weil interne Strukturen dann bereits gewachsen und schwerer zu ändern sind.

Welche Ressourcen definiert man?

Der erste konkrete Schritt bei API-first ist, die fachlichen Ressourcen zu identifizieren – die Objekte, um die sich das System dreht. Eine Ressource ist kein Datenbanktabelle und kein Bildschirm, sondern ein Geschäftsbegriff: Kunde, Bestellung, Rechnung, Termin, Ticket. Für jede Ressource legst du fest:

• Felder und Pflichtangaben. Was gehört zwingend dazu, was ist optional? Ein Kunde braucht zwingend eine Kennung und einen Kontaktweg, eine Rechnungsadresse ist optional.
• Beziehungen zu anderen Ressourcen. Eine Bestellung gehört zu genau einem Kunden und enthält mehrere Positionen – diese Beziehungen bestimmen, wie die Schnittstelle strukturiert wird.
• Erlaubte Aktionen. Nicht jede Ressource erlaubt jede Operation. Eine abgeschlossene Rechnung lässt sich meist nicht mehr ändern, nur stornieren und neu ausstellen.
• Zustände und Übergänge. Viele Ressourcen durchlaufen einen Lebenszyklus – eine Bestellung von „angelegt” über „bezahlt” und „versendet” bis „abgeschlossen”. Welche Übergänge erlaubt sind und welche nicht, gehört in den Entwurf, nicht in verstreute Prüfungen im Code.

Ich gehe bei diesem Schritt gemeinsam mit dem Fachbereich die zentralen Geschäftsvorgänge durch, bevor überhaupt ein Datenmodell entsteht – meist reichen dafür ein bis zwei strukturierte Gespräche plus ein Blick auf bestehende Formulare und Exporte. Der häufigste Fehler an dieser Stelle ist, die Ressourcen aus der vorhandenen Datenbankstruktur abzuleiten statt aus der Fachlichkeit. Das Ergebnis sind Schnittstellen, die technische Altlasten nach außen tragen, statt sie zu verstecken.

Wie funktionieren Versionierung und Auth?

Zwei technische Fragen entscheiden maßgeblich darüber, ob eine Schnittstelle über Jahre stabil bleibt oder bei jeder Änderung Integrationen bricht: Versionierung und Authentifizierung. Beide gehören in den Entwurf, nicht in eine spätere Nachbesserung.

Versionierung. Für die Frage, wann eine Änderung eine neue Version erfordert, ist Semantic Versioning ein bewährtes Grundprinzip: Nur unverträgliche Änderungen an der Schnittstelle – etwa ein entferntes Feld oder ein geändertes Antwortformat – erzwingen eine neue Hauptversion. Neue, optionale Felder oder zusätzliche Endpunkte sind abwärtskompatibel und brauchen keine neue Hauptversion. In der Praxis bedeutet das: Bestehende Konsumenten dürfen nicht plötzlich brechen, wenn du die Schnittstelle erweiterst. Wenn ein Feld wirklich entfernt oder umbenannt werden muss, brauchst du eine Übergangsfrist, in der alte und neue Version parallel laufen, und eine klare Kommunikation an alle bekannten Konsumenten, bis wann die alte Version abgeschaltet wird.

Authentifizierung und Autorisierung. Das sind zwei getrennte Fragen, die häufig vermischt werden. Authentifizierung klärt, wer zugreift – typischerweise über Tokens (etwa API-Keys für Systeme oder OAuth-Tokens für Nutzer:innen), nicht über Benutzername und Passwort im direkten Zugriff. Autorisierung klärt, was diese identifizierte Partei tun darf – welche Ressourcen sie sehen, ändern oder löschen darf. Die OWASP API Security Top 10 führen fehlerhafte Autorisierung auf Objekt- und Funktionsebene als zwei der häufigsten kritischen Schwachstellen bei APIs auf: Systeme prüfen zwar, dass jemand angemeldet ist, aber nicht sauber, ob diese Person genau auf diese Bestellung oder diese administrative Funktion zugreifen darf. Wer eine Schnittstelle entwirft, sollte für jede Ressource und jede Aktion explizit festlegen, welche Rollen sie nutzen dürfen – nicht implizit annehmen, dass ein gültiges Token automatisch vollen Zugriff bedeutet.

Wie testet man Schnittstellen?

Eine Schnittstelle ohne systematisches Testen driftet zuverlässig auseinander – die Dokumentation sagt etwas anderes, als der Code tatsächlich tut, und jeder Konsument merkt das auf die unangenehme Art. Drei Ebenen gehören dazu:

1. Tests gegen die Spezifikation. Wenn die Schnittstelle als offene Spezifikation (etwa im OpenAPI-Format) dokumentiert ist, lassen sich automatisierte Tests direkt dagegen prüfen: Stimmen Feldnamen, Datentypen und Statuscodes mit der Dokumentation überein? Das verhindert, dass Doku und Code auseinanderlaufen – ein Problem, das in gewachsenen Systemen fast immer auftritt, wenn niemand aktiv dagegen arbeitet.
2. Contract-Tests mit echten Konsumenten. Für die wichtigsten Integrationen – die eigene Oberfläche, ein zentraler Partner, ein internes Automatisierungssystem – lohnt sich ein Test, der prüft, ob eine geplante Änderung tatsächlich alles erfüllt, was dieser Konsument braucht. Das findet Probleme, bevor sie in Produktion auffallen.
3. Monitoring im laufenden Betrieb. Manche Fehler zeigen sich erst unter echter Last, mit echten (unsauberen) Daten oder bei Randfällen, die im Test nicht bedacht wurden. Fehlerraten, Antwortzeiten und ungewöhnliche Zugriffsmuster pro Endpunkt gehören überwacht – nicht nur, ob der Dienst grundsätzlich erreichbar ist.

Für kleine Teams ist der pragmatische Einstieg: Stufe 1 ist Pflicht, sobald es eine dokumentierte Spezifikation gibt – der Aufwand ist gering, weil viele Werkzeuge automatisierte Prüfungen direkt aus der Spezifikation ableiten. Stufe 2 lohnt sich, sobald es einen zweiten Konsumenten gibt. Stufe 3 wird spätestens dann nötig, wenn externe Partner oder zahlende Kund:innen auf die Verfügbarkeit angewiesen sind.

Wann ist API-first übertrieben?

API-first ist kein Prinzip, das sich für jedes Projekt lohnt – und Ehrlichkeit an dieser Stelle erspart Unternehmen unnötigen Aufwand. Der Vertragsentwurf, die Versionierungsdisziplin und das Contract-Testing kosten Zeit im Vorfeld. Diese Zeit zahlt sich aus, wenn mehrere Konsumenten dieselbe Schnittstelle nutzen oder absehbar nutzen werden. Sie zahlt sich nicht aus, wenn es dauerhaft nur einen einzigen Konsumenten gibt.

Typische Fälle, in denen der volle API-first-Aufwand übertrieben ist:

• Ein internes Tool für ein kleines Team ohne geplante Integration. Wenn absehbar ist, dass niemand außer der einen Oberfläche je auf die Daten zugreifen wird, lohnt sich der volle Vertragsentwurf selten. Eine einfache, gut strukturierte Schnittstelle reicht – ohne aufwändige Versionsstrategie für Konsumenten, die es nie geben wird.
• Ein Prototyp oder Proof of Concept. In der Phase, in der noch geklärt wird, ob ein Ansatz überhaupt funktioniert, bremst ein vollständiger Schnittstellenvertrag mehr, als er hilft. Hier ist es sinnvoller, schnell zu lernen und die Schnittstelle später sauber nachzuziehen, sobald klar ist, was tatsächlich gebraucht wird.
• Sehr kurzlebige Anwendungen. Wenn ein System von vornherein auf wenige Monate angelegt ist, rechnet sich eine langfristig gedachte Versionierungsstrategie meist nicht.

Der Umkehrschluss gilt genauso: Sobald zwei oder mehr Systeme dieselben Daten brauchen – etwa Web-Oberfläche und mobile App, oder ein internes Tool und ein Partner-Zugang – oder sobald ein KI-Agent Aufgaben automatisiert über die Schnittstelle erledigen soll, kippt die Rechnung deutlich zugunsten von API-first. Der Grund: Jede nachträgliche Vereinheitlichung mehrerer gewachsener Zugriffswege ist aufwändiger als ein Entwurf, der von Anfang an mehrere Konsumenten mitdenkt.

Umsetzung: So gehst du vor

In meinen Projekten hat sich eine Reihenfolge bewährt, die den Aufwand überschaubar hält, ohne die wichtigen Entscheidungen zu überspringen:

1. Ressourcen und Vorgänge sammeln. Gemeinsam mit dem Fachbereich die zentralen Geschäftsobjekte und ihre Lebenszyklen erfassen (siehe oben). Ergebnis: eine Liste von Ressourcen mit Feldern, Beziehungen und Zuständen.
2. Spezifikation entwerfen. Die Schnittstelle als offene Spezifikation dokumentieren, etwa im OpenAPI-Format – lesbar für Menschen und maschinell auswertbar für Tests und Dokumentationswerkzeuge.
3. Mit Konsumenten abstimmen. Wer die Schnittstelle nutzen wird – eigenes Frontend, Partner, künftige Automatisierung – bekommt die Spezifikation vor der Umsetzung zu sehen. Häufig zeigt sich hier schon, dass ein Feld fehlt oder ein Datenformat unpraktisch ist – deutlich billiger zu ändern als nach der Implementierung.
4. Versionierungs- und Auth-Strategie festlegen. Wie oben beschrieben: Regeln für Breaking Changes, Übergangsfristen, Authentifizierungsmethode und Rollenmodell – bevor der erste produktive Zugriff erfolgt.
5. Implementieren und gegen die Spezifikation testen. Der Code setzt die Spezifikation um; automatisierte Tests stellen sicher, dass beides übereinstimmt.
6. Dokumentation und Zugriff bereitstellen. Konsumenten brauchen nicht nur die Spezifikation, sondern auch, wie sie an Zugangsdaten kommen und wo sie Änderungen erfahren – etwa über ein Änderungsprotokoll.

Diese Reihenfolge lässt sich skalieren: Für ein kleines internes Tool reichen oft ein informelles Dokument statt einer vollständigen OpenAPI-Spezifikation und ein einfacher API-Key statt eines vollständigen OAuth-Flows. Wichtig ist das Prinzip – Vertrag vor Umsetzung –, nicht die Schwere des Werkzeugs.

Risiken & Grenzen

• Overengineering am Anfang. Der häufigste Fehler bei API-first ist nicht zu wenig, sondern zu viel Vorabplanung für Anwendungsfälle, die es nie geben wird. Plane für die Konsumenten, die absehbar kommen – nicht für jeden denkbaren.
• Vertrag ohne Durchsetzung. Eine Spezifikation, gegen die niemand testet, verkommt zur Dokumentation, die nicht mehr stimmt. Ohne automatisierte Prüfung lohnt sich der Entwurfsaufwand nur halb.
• Fehlerhafte Autorisierung bleibt das Hauptrisiko. Laut OWASP API Security Top 10 sind Schwächen bei der Autorisierung auf Objekt- und Funktionsebene die am häufigsten ausgenutzten API-Schwachstellen. Ein guter Schnittstellenentwurf beschreibt, was möglich ist – er ersetzt nicht die Prüfung, wer worauf zugreifen darf, bei jeder einzelnen Anfrage.
• Neue Risiken durch KI-Anbindung. Sobald eine Schnittstelle auch von KI-Agenten oder generativen Modellen angesprochen wird, entstehen laut BSI neuartige IT-Sicherheitsrisiken zusätzlich zu den klassischen – etwa wenn ein Agent auf Basis unsicherer Eingaben Aktionen auslöst, die eigentlich eine menschliche Prüfung bräuchten. Wer Schnittstellen für solche Anwendungsfälle öffnet, sollte Aktionen mit Folgen (Zahlungen, Löschungen, Vertragsänderungen) zusätzlich absichern – etwa durch eine Bestätigung oder engere Berechtigungen als bei menschlichen Nutzer:innen.
• Kosten und Zeit sind Bandbreiten, keine Zusagen. Der zusätzliche Aufwand für einen sauberen API-first-Entwurf hängt stark von Anzahl und Komplexität der Ressourcen sowie der Zahl der Konsumenten ab. Als grobe Einordnung aus meiner Projekterfahrung: Für ein überschaubares internes Tool mit wenigen Ressourcen bewegt sich der zusätzliche Planungsaufwand gegenüber einem direkten Start meist im Bereich weniger Tage; bei mehreren Ressourcen, mehreren Konsumenten und einem vollständigen Rollenmodell kann er sich auf mehrere Wochen ausweiten. Das sind Erfahrungswerte, keine verbindliche Kalkulation – die genaue Zahl hängt vom konkreten Projekt ab.

Checkliste: API-first entwickeln

Schritt	Frage	Erledigt?
Ressourcen	Sind die fachlichen Ressourcen mit Feldern, Beziehungen und Zuständen definiert – nicht aus der Datenbank abgeleitet?
Spezifikation	Liegt eine dokumentierte, maschinenlesbare Spezifikation vor (z. B. im OpenAPI-Format)?
Abstimmung	Haben alle bekannten Konsumenten die Spezifikation vor der Umsetzung gesehen?
Versionierung	Ist geregelt, welche Änderungen abwärtskompatibel sind und wie Breaking Changes kommuniziert werden?
Auth	Sind Authentifizierung (wer greift zu) und Autorisierung (was darf diese Partei) getrennt und für jede Ressource festgelegt?
Autorisierung je Objekt	Wird geprüft, ob eine Partei genau auf dieses Objekt zugreifen darf – nicht nur, ob sie angemeldet ist?
Tests	Gibt es automatisierte Tests gegen die Spezifikation und, bei mehreren Konsumenten, Contract-Tests?
Monitoring	Werden Fehlerraten und ungewöhnliche Zugriffsmuster pro Endpunkt beobachtet?
KI-Zugriff	Sind Aktionen mit Folgen (Zahlung, Löschung, Vertrag) zusätzlich abgesichert, falls ein KI-Agent zugreifen darf?
Verhältnismäßigkeit	Gibt es mehr als einen absehbaren Konsumenten – oder lohnt sich der volle Aufwand (noch) nicht?

Eigene Checkliste Philogic Labs, abgeleitet aus Umsetzungsprojekten.

Wenn du unsicher bist, ob sich der volle API-first-Aufwand für dein Vorhaben lohnt oder wie eine bestehende Schnittstelle sauber nachgezogen werden kann: Wir prüfen Scope und Architektur im Rahmen unseres Beratungsangebots, bauen interne Tools und Kundenportale auch direkt um eine API-first-Architektur herum, und für Teams, die ihre Mitarbeitenden im Umgang mit Schnittstellen und KI-Werkzeugen fit machen wollen, gibt es passende Schulungen. Wer Produktdaten zusätzlich für KI-Shopping-Assistenten zugänglich machen will, findet dazu mehr unter Agent-Ready.