Wie gestaltet und entwickelt man Git-native APIs?

Die meisten API-Teams behandeln den Vertrag als Nebensache. Sie schreiben zuerst Code, generieren dann eine Spezifikation und sehen zu, wie die beiden auseinanderdriften. Git-natives API-Design kehrt diese Reihenfolge um. Sie behandeln den API-Vertrag als Quellcode, versionieren ihn in Git und überprüfen jede Änderung auf die gleiche Weise, wie Sie Anwendungslogik überprüfen.

Dieser Leitfaden handelt von der Disziplin, nicht von einem einzelnen Tool. Sie lernen, wie Sie Verträge in Branches entwerfen, diese in Pull Requests überprüfen und eine committete Spezifikation in Mocks, Tests und Dokumente umwandeln. Ziel ist ein Workflow, bei dem Ihre Git-Historie *Ihre* API-Historie *ist*.

Wenn Sie bereits wissen, wie Spec-First-Tools aussehen und eine Produktführung wünschen, lesen Sie den Begleitartikel zum git-nativen API-Workflow. Dieser Artikel konzentriert sich auf die Praxis.

Was „Git-nativ“ für die API-Arbeit bedeutet

Git-nativ bedeutet, dass Ihre API-Definition als einfache Textdatei in Ihrem Repository liegt. Nicht in einer proprietären Cloud-Datenbank. Nicht hinter einem Anbieter-Login. Eine .yaml- oder .json-Datei, die neben Ihrem Code liegt und mit der gleichen Versionskontrolle verfolgt wird, die Ihr Team bereits verwendet.

Vergleichen Sie dies mit Cloud-gebundenen Tools. Viele API-Design-Plattformen speichern den Vertrag in ihrem eigenen Backend. Sie bearbeiten über eine Web-UI, und die kanonische Version befindet sich auf ihren Servern. Ihr Repo enthält bestenfalls einen veralteten Export. Wenn die Datenbank des Anbieters die Quelle der Wahrheit ist, sagt Ihre Git-Historie nichts darüber aus, wie sich die API entwickelt hat.

Das Git-native-Modell kehrt diese Beziehung um. Die Datei in main ist der Vertrag. Alles andere, einschließlich jeder GUI, ist eine Ansicht dieser Datei. Diese einzige Verschiebung ermöglicht Historie, Blame, Rollback und Überprüfung für Ihre API-Oberfläche.

Ein Git-native Setup hat drei Eigenschaften. Die Spezifikation ist eine Textdatei im Repo. Änderungen erfolgen über normale Git-Operationen wie Branch, Commit und Merge. Und jedes nachgelagerte Artefakt, von Mocks bis zu Dokumenten, leitet sich von der committeten Datei ab und nicht von einer separaten Datenbank.

Warum APIs in Git entwerfen und entwickeln

Sie vertrauen Git bereits Ihr wertvollstes Gut an: Ihren Code. Ihr API-Vertrag verdient die gleiche Behandlung.

Die Historie ist der erste Grund. Wenn jemand fragt: „Wann haben wir den cursor-Paginierungsparameter hinzugefügt?“, antwortet git log in Sekundenschnelle. Der Commit, der ihn eingeführt hat, enthält eine Nachricht, einen Autor und ein Datum. Keine Screenshots, keine Changelog-Archäologie.

Blame ist der zweite. Führen Sie git blame für die Spezifikationsdatei aus und Sie sehen genau, wer jede Zeile geändert hat und warum. Ein verwirrender Feldname lässt sich auf den PR zurückführen, der ihn hinzugefügt hat, mit der angehängten Diskussion. Verantwortlichkeit wird automatisch.

Rollback ist der dritte. Ein schlechtes Design wird ausgeliefert. Mit Git können Sie den Merge mit git revert rückgängig machen und der Vertrag kehrt in seinen früheren Zustand zurück. Nachgelagerte Codegen, Mocks und Dokumente werden aus der zurückgesetzten Datei neu generiert. Es gibt keine manuelle Bereinigung in einem separaten System.

Review ist der vierte Grund, und es ist der, den Teams zu wenig nutzen. Ein Pull Request ist der natürliche Ort, um ein API-Design zu diskutieren, *bevor* es real wird. Reviewer kommentieren eine +-Zeile, die ein Pflichtfeld hinzufügt. Die Konversation bleibt für immer neben der Änderung bestehen.

Die einzige Quelle der Wahrheit verbindet alles. Wenn der Vertrag eine Datei in main ist, gibt es keine Unklarheit darüber, welche Version real ist. Frontend, Backend, QA und Dokumente lesen alle dieselbe YAML-Zeile. Dies ist das Kernversprechen eines Git-basierten API-Spezifikations-Workflows.

Der Git-native API-Design-Loop

Der Loop besteht aus fünf Schritten: Entwurf des Vertrags, Commit, Öffnen eines PRs, Review und Merge. Die Implementierung folgt dem Merge, nicht umgekehrt.

Beginnen Sie mit dem Schreiben des Vertrags. Angenommen, Sie fügen einen Endpunkt hinzu, um die Rechnungen eines Benutzers abzurufen. Sie erstellen einen Branch und bearbeiten die OpenAPI-Datei.

# openapi.yaml (excerpt added on branch feat/invoices-list)
paths:
 /users/{userId}/invoices:
 get:
 operationId: listUserInvoices
 summary: List invoices for a user
 parameters:
 - name: userId
 in: path
 required: true
 schema: { type: string, format: uuid }
 - name: status
 in: query
 required: false
 schema:
 type: string
 enum: [draft, open, paid, void]
 responses:
 "200":
 description: A page of invoices
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/InvoiceList"
 "404":
 description: User not found

Committen Sie diese Änderung mit einer klaren Nachricht: git commit -m "Add GET /users/{userId}/invoices contract". Der Commit ist klein und fokussiert. Er beschreibt eine Designentscheidung.

Öffnen Sie nun einen Pull Request. Der Diff zeigt den Reviewern genau, was neu ist: ein Pfad, eine Operation, zwei Parameter, zwei Antworten. Ihre Teamkollegen diskutieren die Benennung, die Enum-Werte und ob 404 der richtige Code für einen fehlenden Benutzer ist. Sie könnten auf eine Cursor-Paginierung drängen, noch bevor eine einzige Zeile Handler-Code existiert.

Sobald der PR genehmigt ist, mergen Sie ihn. Der Vertrag in main enthält nun den Rechnungs-Endpunkt. Die Implementierung folgt als Nächstes und wird durch die Spezifikation eingeschränkt, auf die sich alle geeinigt haben. Diese Reihenfolge ist das, was man unter Spec-First API-Entwicklung versteht: Die Vereinbarung geht dem Code voraus.

Der Vorteil ist, dass Design-Diskussionen kostengünstig sind. Das Ändern eines YAML-Feldes im Review kostet Minuten. Das Ändern eines ausgelieferten, implementierten und dokumentierten Endpunkts kostet Tage.

Branching-Strategie für API-Verträge

Behandeln Sie Vertragsänderungen wie jede andere Änderung: ein Branch pro logischer Arbeitseinheit. Ein Branch pro Endpunkt oder pro Modifikation hält PRs klein und Diffs lesbar.

Benennen Sie Branches so, dass die Absicht offensichtlich ist. Verwenden Sie ein Präfix, das die Änderungsklasse signalisiert. Dies hilft Reviewern und CI, die Arbeit zu steuern.

Das Präfix trägt Bedeutung. Ein break/api--Branch weist Reviewer an, langsamer zu machen und jeden Consumer zu überprüfen. Ein chore/api--Branch signalisiert keine semantische Änderung, sodass der Review schnell erfolgen kann.

Sie wählen auch ein Branching-Modell. Trunk-based Development eignet sich für die meisten API-Teams. Kurzlebige Branches werden täglich in main gemergt, und die Spezifikation bleibt nah an einer einzigen Wahrheit. Gitflow, mit langlebigen develop- und release-Branches, passt zu Teams, die API-Änderungen in geplante Releases bündeln.

Für die meisten API-Arbeiten ist Trunk-basiertes Vorgehen vorzuziehen. Kleine, häufige Vertragsänderungen erzeugen kleine, häufige Diffs. Langlebige Branches lassen die Spezifikation driften, und YAML-Merge-Konflikte werden schnell unübersichtlich, wenn zwei Branches dieselbe Datei umstrukturieren.

Überprüfung des API-Designs in Pull Requests

Ein Spezifikations-PR ist ein Design-Review, keine Syntaxprüfung. Reviewer achten auf die Semantik, und ein paar Fragen decken den größten Teil des Risikos ab.

Bricht dies bestehende Consumer? Das Entfernen eines Feldes, das Umbenennen eines Pfades oder das Verschärfen eines Typs sind alles Breaking Changes. Ein Reviewer prüft, ob die Änderung additiv oder breaking ist, und Breaking Changes erfordern einen Versions-Bump oder einen Deprecation-Pfad.

Ist die Benennung konsistent? Wenn jeder Sammlungs-Endpunkt Plural-Substantive verwendet, fällt ein neuer singularer Pfad auf. Wenn Fehler anderswo ein code-Feld zurückgeben, sollte ein neuer Endpunkt dies auch tun. Reviewer setzen die bereits etablierten API-Muster durch.

Ist es Diff-freundlich? Halten Sie das YAML stabil, damit Diffs klein bleiben. Ordnen Sie Schlüssel konsistent an. Fügen Sie neue Pfade an einer vorhersehbaren Stelle hinzu. Ein Reviewer kann einen Fünf-Zeilen-Diff in Sekunden lesen, aber eine neu geordnete Datei erzeugt einen Hundert-Zeilen-Diff, der die tatsächliche Änderung verbirgt.

Reviewer-freundlicher Breaking Change. Die --Zeilen markieren genau, was verschwindet.

# Diff a reviewer sees in the PR
 parameters:
 - name: status
 in: query
 schema:
 type: string
- enum: [draft, open, paid, void]
+ enum: [draft, open, paid, void, uncollectible]

Dieser Diff ist additiv zum Enum, daher ist er sicher. Vergleichen Sie ihn mit einer --Zeile, die void vollständig entfernt, was jeden Client, der diesen Wert sendet, brechen würde. Der Diff macht den Unterschied auf einen Blick sichtbar.

Ermutigen Sie Reviewer, Kommentare direkt in der Spezifikation zu hinterlassen, genauso wie sie Kommentare im Code hinterlassen. Die Diskussion bleibt an die Zeile gebunden und überlebt in der gemergten Historie.

Vom Design zur Entwicklung

Sobald der Vertrag in main ist, wird er zur Quelle für alles Nachgelagerte. Sie generieren, Sie schreiben nicht manuell.

Zuerst kommt Codegen. Tools wie openapi-generator erzeugen Server-Stubs und typisierte Clients aus der committeten Datei. Ihre Handler füllen die Geschäftslogik aus, aber die Anforderungs- und Antwortformen entsprechen dem Vertrag konstruktionsbedingt. Die Spezifikation und der Code können sich nicht über das Wire-Format uneinig sein.

Als Nächstes kommen Mocks. Ein Mock-Server liest die Spezifikation und gibt Beispielantworten für jeden Endpunkt zurück. Frontend-Entwickler entwickeln gegen den Mock, bevor das Backend existiert. Sie beginnen in dem Moment, in dem der Vertrag gemergt wird, nicht Wochen später.

Tests folgen. Vertragstests stellen sicher, dass Ihr laufender Server der Spezifikation entspricht. Senden Sie eine Anfrage, validieren Sie die Antwort gegen das Schema und lassen Sie den Build fehlschlagen, wenn sie voneinander abweichen. Dies ist die Leitplanke gegen Spec/Code-Drift.

Auch Dokumente werden generiert. Referenzdokumentation wird direkt aus der OpenAPI-Datei gerendert. Wenn sich der Vertrag ändert, ändern sich die Dokumente im selben Commit. Es gibt kein separates Dokumenten-Update, das man vergessen könnte.

Das Prinzip ist konsistent. Jedes Artefakt leitet sich von einer committeten Datei ab. Generieren Sie bei jedem Merge neu, und Ihre Mocks, Clients, Tests und Dokumente bleiben synchron mit dem Vertrag.

Teamkonventionen, die skalieren

Konventionen sind das, was einen Git-nativen Workflow vor dem Kollaps bewahrt, wenn das Team wächst. Legen Sie sie frühzeitig fest und schreiben Sie sie auf.

Wählen Sie zuerst zwischen einer Spezifikationsdatei und vielen. Eine einzelne openapi.yaml ist einfach, wird aber nach ein paar Dutzend Endpunkten unhandlich. Das Aufteilen in mehrere Dateien mit $ref-Referenzen hält jede Datei lesbar, auf Kosten eines Bündelungsschritts. Ein gängiges Muster ist eine Datei pro Ressource, die zur Build-Zeit zu einer einzigen Spezifikation gebündelt wird.

Zweitens, versionieren Sie bewusst. Erhöhen Sie die OpenAPI info.version bei jeder sinnvollen Änderung und folgen Sie der semantischen Versionierung. Additive Änderungen erhöhen die Minor-Version. Breaking Changes erhöhen die Major-Version und bedeuten normalerweise ein neues Pfadpräfix wie /v2/.

Drittens, führen Sie ein Changelog. Eine CHANGELOG.md neben der Spezifikation dokumentiert, was sich geändert hat und warum, in verständlichen Worten. Die Git-Historie ist präzise, aber ausführlich; das Changelog ist die lesbare Zusammenfassung, die Ihre Consumer tatsächlich durchsehen.

Viertens, schützen Sie die Spezifikation mit CODEOWNERS. Verlangen Sie von API-Stewards, jede Änderung an der Vertragsdatei zu genehmigen. Dies verhindert, dass wohlmeinende Mitwirkende inkonsistente Designs ausliefern.

# .github/CODEOWNERS
/api/openapi.yaml @api-stewards
/api/paths/ @api-stewards

Fünftens, linten Sie in CI. Ein Linter fängt Stil- und Konsistenzprobleme vor dem Review ab. Führen Sie ihn bei jedem PR aus, damit Menschen das Design überprüfen und nicht die Formatierung.

# .github/workflows/api-lint.yml
name: API Lint
on:
 pull_request:
 paths: ["api/"]
jobs:
 spectral:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Run Spectral
 run: npx @stoplight/spectral-cli lint api/openapi.yaml --fail-severity warn

Mit CI-Linting plus CODEOWNERS erhält jede Vertragsänderung automatisierte Prüfungen und einen menschlichen Verantwortlichen. Diese Kombination skaliert von drei Ingenieuren auf dreihundert.

Häufige Fallstricke und wie man sie vermeidet

Git-natives API-Design hat vorhersehbare Fehlerquellen. Wenn man sie kennt, kann man sie umgehen.

Spec/Code-Drift ist das Schlimmste. Der Vertrag sagt das Eine; der laufende Server tut das Andere. Verhindern Sie dies mit Vertragstests in CI, die Live-Antworten gegen die committete Spezifikation validieren. Wenn sie abweichen, schlägt der Build fehl. Drift wird zu einer unterbrochenen Pipeline, nicht zu einer Überraschung in der Produktion.

Riesige PRs sind die nächste Falle. Ein einzelner Branch, der zwanzig Endpunkte hinzufügt, erzeugt einen nicht überprüfbaren Diff. Reviewer überfliegen, genehmigen und übersehen Probleme. Teilen Sie die Arbeit in einen Endpunkt oder eine Änderung pro PR auf. Kleine Diffs erhalten eine echte Überprüfung.

Manuell geschriebene Artefakte verursachen stille Inkonsistenzen. Wenn jemand einen Client manuell schreibt, anstatt ihn zu generieren, weicht der Client von der Spezifikation ab. Generieren Sie Clients, Stubs und Dokumente jedes Mal aus der committeten Datei. Behandeln Sie manuell geschriebene API-Artefakte als Warnsignal.

YAML-Merge-Konflikte frustrieren Teams auf langlebigen Branches. Zwei Branches strukturieren dieselbe Datei neu, und Git kann sie nicht abgleichen. Vermeiden Sie dies mit kurzlebigen Branches, einer stabilen Schlüsselreihenfolge und einem Split-File-Layout, sodass Änderungen verschiedene Dateien betreffen. Trunk-basiertes Development plus kleine PRs beseitigt die meisten Konflikte, bevor sie entstehen.

Das Muster bei allen vier Punkten ist dasselbe. Halten Sie Änderungen klein, leiten Sie Artefakte von der Spezifikation ab und lassen Sie CI den Vertrag durchsetzen. Disziplin schlägt Heldentaten.

Wo Apidog passt

Sie können einen Git-nativen Workflow mit einem Texteditor und einer CLI betreiben. Viele Teams wünschen sich eine GUI für das Design, ohne Git als Single Source of Truth aufzugeben. Das ist die Lücke, die der Spec-First-Modus von Apidog füllt.

Der Spec-First-Modus hält die OpenAPI-Datei in Ihrem Git-Repository und verfügt über eine bidirektionale Synchronisierung. Sie bearbeiten den Vertrag im visuellen Designer von Apidog oder in Ihrem Editor, und beide bleiben mit der Datei in Ihrem Repo konsistent. Die Datei in Git bleibt kanonisch, sodass Branches, PRs und die Historie genau wie hier beschrieben funktionieren. Sie erhalten die GUI ohne Cloud-Lock-in. Einzelheiten zur Einrichtung finden Sie in der Spec-First Mode Dokumentation.

Es geht nicht um das Tool. Es geht darum, dass Sie gleichzeitig eine visuelle Designoberfläche und eine Git-native Disziplin haben können. Das Repo bleibt die einzige Quelle der Wahrheit, und Apidog wird zu einer Ansicht darauf.

FAQ

Ist Git-natives API-Design nur für OpenAPI?

Nein. Die Disziplin gilt für jedes textbasierte Vertragsformat. OpenAPI ist das gängigste, aber derselbe Workflow funktioniert auch für AsyncAPI, gRPC-.proto-Dateien oder GraphQL SDL. Solange der Vertrag eine Textdatei ist, die Sie diffen, verzweigen und überprüfen können, ist sie Git-nativ.

Wie gehe ich mit Breaking Changes in einem Git-nativen Workflow um?

Machen Sie Breaking Changes sichtbar und bewusst. Verwenden Sie ein break/api--Branch-Präfix, erhöhen Sie die Major-Version und verlangen Sie eine Abnahme durch einen Steward über CODEOWNERS. Fügen Sie, wo möglich, die neue Form neben der alten hinzu und deprecaten Sie den alten Pfad nach einem Zeitplan. Der PR-Diff und der Versions-Bump signalisieren zusammen die Änderung jedem Consumer.

Soll die API-Spezifikation im selben Repo wie der Code leben?

Normalerweise ja, wenn ein Team beides besitzt. Die Koexistenz von Spezifikation und Implementierung bedeutet, dass ein einzelner PR den Vertrag und den Handler zusammen ändern kann und Vertragstests in einer Pipeline ausgeführt werden. Legen Sie die Spezifikation nur dann in ein separates Repo, wenn viele Teams eine gemeinsame API konsumieren und eine unabhängige Versionierung benötigen.

Wie verhindere ich, dass Spezifikation und Code auseinanderdriften?

Fügen Sie Vertragstests zu CI hinzu. Diese senden echte Anfragen an Ihren laufenden Server und validieren jede Antwort gegen die committete Spezifikation. Eine Abweichung führt zum Fehlschlagen des Builds. In Kombination mit der Generierung von Stubs und Clients aus der Spezifikation machen Vertragstests den Drift zu einem Pipeline-Fehler statt zu einem Produktionsfehler.

Fazit

Git-natives API-Design ist eine Disziplin, kein Produkt. Sie behandeln den Vertrag als Quellcode, entwickeln ihn in Branches, überprüfen ihn in Pull Requests und generieren jedes nachgelagerte Artefakt aus der committeten Datei. Historie, Blame, Rollback und Überprüfung erhalten Sie kostenlos, da Git Ihnen diese bereits bietet.

Fangen Sie klein an. Verschieben Sie Ihre Spezifikation in das Repo, fügen Sie einen Lint-Schritt hinzu und verlangen Sie eine Überprüfung bei Vertragsänderungen. Bauen Sie darauf auf mit Codegen, Mocks und Vertragstests. Der Workflow potenziert sich: Jede Konvention erleichtert die nächste, und Ihre Git-Historie wird zu einer vollständigen Aufzeichnung, wie Ihre API gewachsen ist.

Wenn Sie eine visuelle Designoberfläche wünschen, die die Spezifikation in Git hält, probieren Sie den Spec-First-Modus in Apidog aus und sehen Sie, wie die bidirektionale Synchronisierung in den oben beschriebenen Workflow passt.