Ohne schriftlichen API-Vertrag entwickeln beide Seiten aneinander vorbei. Was passiert, wenn der Vertrag fehlt — und was ein guter API-Vertrag enthält.
Zwei Systeme sollen miteinander reden. System A schickt Daten, System B empfängt sie. Klingt einfach. Und es wäre einfach, wenn beide Seiten von Anfang an genau wüssten, was übertragen wird, in welchem Format, zu welchem Zeitpunkt, und was passiert, wenn etwas schiefgeht.
In der Praxis läuft es häufig so: Beide Seiten fangen an zu entwickeln. Irgendwann treffen die Systeme aufeinander — und dann stellt sich heraus, dass System A Datumsfelder als String sendet, System B aber ein ISO-8601-Format erwartet. Oder dass System A Artikelnummern mit führenden Nullen liefert, die System B stillschweigend abschneidet. Oder dass der Endpunkt, gegen den entwickelt wurde, in der Zwischenzeit umbenannt wurde.
Das sind keine Ausnahmefälle. Das ist der Normalfall, wenn kein API-Vertrag existiert.
Ein API-Vertrag ist ein schriftliches Dokument, das vor Beginn der Entwicklung zwischen allen beteiligten Parteien vereinbart und freigegeben wird. Es beschreibt verbindlich, wie die Schnittstelle funktioniert — nicht wie sie irgendwann funktionieren soll, sondern wie sie funktionieren wird.
Ein API-Vertrag ist kein Pflichtenheft und keine technische Dokumentation, die nachträglich erstellt wird. Er ist eine Vereinbarung, die Grundlage für die Entwicklung beider Seiten ist.
Endpunkte und Methoden. Welche URLs gibt es? Welche HTTP-Methoden (GET, POST, PUT, DELETE) werden verwendet? Wie ist die Basis-URL aufgebaut?
Request-Struktur. Welche Felder werden gesendet? Welche sind Pflicht, welche optional? Welche Datentypen werden erwartet (String, Integer, Boolean, Datum)?
Response-Struktur. Wie sieht die Antwort bei Erfolg aus? Welche Felder enthält sie? In welchem Format werden Datumsangaben geliefert?
Fehlercodes. Welche HTTP-Statuscodes werden verwendet? Was bedeutet jeder Code? Wie sieht die Fehlerantwort strukturell aus? Das ist oft der am schlechtesten dokumentierte Teil — und der wichtigste für robuste Systeme.
Authentifizierung. Wie wird die Verbindung abgesichert? API-Key, OAuth, Basic Auth? Wo wird das Token übergeben?
Rate Limits und Verfügbarkeit. Wie viele Anfragen sind pro Minute erlaubt? Was passiert bei Überschreitung? Welche Verfügbarkeitszeiten werden garantiert?
Beispiele. Konkrete Beispiele für Request und Response — keine abstrakten Schemata, sondern echte JSON-Beispiele mit realistischen Werten. Beispiele sind oft klarer als jede Beschreibung.
Ein API-Vertrag beschreibt die Schnittstelle — nicht die Implementierung dahinter. Wie System B intern die Daten verarbeitet, ist nicht Teil des Vertrags. Was zählt, ist das Verhalten nach außen.
Auch keine Zukunftsversprechen: "Wir planen später noch weitere Endpunkte" gehört nicht in den Vertrag. Was drin steht, muss umsetzbar und verbindlich sein.
Ohne schriftliche Vereinbarung entwickeln beide Seiten gegen ihre eigenen Annahmen. Das funktioniert so lange, bis die Systeme zum ersten Mal zusammentreffen. Dann beginnt die eigentliche Arbeit: herausfinden, wo die Annahmen auseinandergingen, Korrekturen abstimmen, neu entwickeln.
Dieser Zusatzaufwand ist vollständig vermeidbar. Er entsteht nicht durch technische Komplexität — er entsteht durch fehlende Kommunikation zu Beginn des Projekts.
In der Regel erstellt die Seite den ersten Entwurf, die die API bereitstellt. Die andere Seite prüft, ob alle notwendigen Felder und Endpunkte enthalten sind. Beide Seiten geben das Dokument schriftlich frei, bevor die Entwicklung beginnt.
Bei Projekten, die wir begleiten, ist die Fertigstellung und Freigabe des API-Vertrags ein expliziter Meilenstein im Projektplan. Ohne Freigabe beginnt keine Entwicklung.
Wir klären den API-Vertrag bevor wir eine Zeile Code schreiben.