Wie gestaltet und entwickelt man Git-native APIs?

Die meisten API-Teams behandeln den Vertrag als Nebensache: erst Code, dann Spezifikation, danach Drift. Git-natives API-Design dreht das um. Sie behandeln den API-Vertrag als Quellcode, versionieren ihn in Git und reviewen jede Änderung wie Anwendungslogik.

Teste Apidog noch heute

Dieser Leitfaden zeigt einen praktischen Workflow: Verträge in Branches entwerfen, per Pull Request prüfen und aus der gemergten Spezifikation Mocks, Tests, Clients und Dokumentation erzeugen. Ziel: Ihre Git-Historie ist Ihre API-Historie.

Wenn Sie eine Produktführung zu Spec-First-Tools suchen, lesen Sie den Begleitartikel zum git-nativen API-Workflow. Dieser Artikel konzentriert sich auf die Umsetzung.

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

Git-nativ heißt: Ihre API-Definition liegt als Textdatei im Repository, z. B. als openapi.yaml oder openapi.json. Nicht nur als Export. Nicht ausschließlich in einer proprietären Cloud-Datenbank. Die Datei im Repo ist die kanonische Quelle.

Das Modell ist einfach:

1. Die Spezifikation liegt im Repo.
2. Änderungen erfolgen über Branches, Commits und Pull Requests.
3. Nachgelagerte Artefakte wie Mocks, Clients, Tests und Dokumentation werden aus der committeten Datei erzeugt.

Damit werden Git-Funktionen direkt auf die API-Oberfläche anwendbar:

• git log zeigt, wann ein Endpunkt oder Feld eingeführt wurde.
• git blame zeigt, wer eine Vertragszeile geändert hat.
• git revert kann ein schlechtes API-Design zurücknehmen.
• Pull Requests werden zum Ort für API-Design-Reviews.

Warum APIs in Git entwerfen?

Sie versionieren Ihren Code in Git. Der API-Vertrag sollte denselben Status haben.

1. Historie

Wenn jemand fragt, wann der Query-Parameter cursor eingeführt wurde, liefert Git die Antwort:

git log -S "cursor" -- api/openapi.yaml

Sie sehen Commit, Autor, Datum und PR-Kontext.

2. Verantwortlichkeit

Mit git blame finden Sie heraus, warum ein Feld existiert:

git blame api/openapi.yaml

Das ist besonders hilfreich bei unklaren Namen, alten Pfaden oder inkonsistenten Fehlerformaten.

3. Rollback

Wenn eine Vertragsänderung falsch war:

git revert <merge-commit>

Danach werden Mocks, Clients, Tests und Dokumente aus der zurückgesetzten Spezifikation neu erzeugt.

4. Review vor Implementierung

Ein Pull Request ist der richtige Ort, um API-Design zu prüfen, bevor Handler-Code existiert. Reviewer können direkt an der YAML-Zeile kommentieren, z. B. bei neuen Pflichtfeldern, Statuscodes oder Enum-Werten.

Das ist das Kernversprechen eines Git-basierten API-Spezifikations-Workflows: Eine Datei in main ist die Single Source of Truth.

Der Git-native API-Design-Loop

Ein praktikabler Loop besteht aus fünf Schritten:

1. Branch erstellen
2. Vertrag ändern
3. Commit erstellen
4. Pull Request öffnen
5. Reviewen und mergen

Die Implementierung folgt erst danach.

Beispiel: Sie fügen einen Endpunkt hinzu, um Rechnungen eines Benutzers abzurufen.

git checkout -b feat/api-invoices-list

Dann ändern Sie die OpenAPI-Datei:

# api/openapi.yaml
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

Commit:

git add api/openapi.yaml
git commit -m "Add GET /users/{userId}/invoices contract"

Im Pull Request prüfen Reviewer:

• Ist der Pfad konsistent benannt?
• Sind Statuscodes korrekt?
• Braucht die Liste Pagination?
• Ist 404 für einen fehlenden Benutzer passend?
• Sind Enum-Werte stabil und verständlich?

Nach dem Merge ist der Vertrag in main. Erst jetzt implementieren Backend und Frontend gegen die vereinbarte Spezifikation. Genau das ist Spec-First API-Entwicklung: Die Vereinbarung kommt vor dem Code.

Branching-Strategie für API-Verträge

Halten Sie Vertragsänderungen klein. Ein Branch sollte eine logische Änderung enthalten: ein neuer Endpunkt, ein neues Feld, ein Bugfix oder ein Breaking Change.

Änderungstyp	Branch-Präfix	Beispiel	Review-Gewicht
Neuer Endpunkt	feat/api-	feat/api-invoices-list	Standard
Additives Feld	feat/api-	feat/api-invoice-currency	Leicht
Breaking Change	break/api-	break/api-remove-legacy-id	Schwer, benötigt Abnahme
Bugfix in Spezifikation	fix/api-	fix/api-status-enum-typo	Leicht
Nur Refactoring	chore/api-	chore/api-reorder-schemas	Leicht

Das Präfix hilft Reviewern und CI. Ein break/api--Branch signalisiert: genau prüfen, Consumer einbeziehen, Versionierung beachten.

Für die meisten Teams ist Trunk-based Development sinnvoller als langlebige Branches.

Modell	Am besten für	API-Kompromiss
Trunk-basiert	Continuous Delivery, kleine bis mittlere Teams	Kleine Diffs, weniger Merge-Konflikte
Gitflow	Geplante Releases, regulierte Auslieferung	Längere Divergenz, größere Merges

Empfehlung: kurzlebige Branches, kleine PRs, häufige Merges nach main.

API-Design in Pull Requests reviewen

Ein Spezifikations-PR ist kein reiner Syntax-Check. CI kann Formatierung und Linting übernehmen. Menschen sollten Semantik reviewen.

Nutzen Sie diese Checkliste:

Bricht die Änderung bestehende Consumer?

Breaking Changes sind z. B.:

• Feld entfernen
• Pflichtfeld hinzufügen
• Pfad umbenennen
• Typ verschärfen
• Enum-Wert entfernen
• Response-Format ändern

Additive Änderungen sind meistens sicherer, z. B. ein optionales Feld oder ein neuer Enum-Wert.

Beispiel-Diff:

parameters:
  - name: status
    in: query
    schema:
      type: string
-     enum: [draft, open, paid, void]
+     enum: [draft, open, paid, void, uncollectible]

Das ist additiv. Würde void entfernt, wäre es potenziell breaking.

Ist die Benennung konsistent?

Prüfen Sie bestehende API-Konventionen:

• Verwenden Sammlungen Pluralformen?
• Sind IDs einheitlich benannt?
• Haben Fehlerantworten überall dasselbe Schema?
• Folgen Query-Parameter einem bekannten Muster?

Ist der Diff lesbar?

Stabile YAML-Struktur ist wichtig. Vermeiden Sie unnötiges Reformatieren der gesamten Datei. Sonst versteckt ein großer Diff die eigentliche API-Änderung.

Praktische Regeln:

• Schlüsselreihenfolge beibehalten
• neue Pfade an erwartbarer Stelle einfügen
• kein Auto-Format der gesamten Spezifikation im selben PR
• Refactorings getrennt von semantischen Änderungen durchführen

Vom Design zur Entwicklung

Nach dem Merge wird die Spezifikation zur Quelle für alle nachgelagerten Artefakte.

1. Code generieren

Tools wie openapi-generator können Server-Stubs oder Clients aus der Spezifikation erzeugen.

Beispiel:

npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o generated/client

Die Geschäftslogik schreiben Sie weiterhin selbst. Aber Request- und Response-Formen folgen dem Vertrag.

2. Mocks bereitstellen

Ein Mock-Server liest die OpenAPI-Datei und liefert Beispielantworten. Frontend-Teams können gegen den Vertrag entwickeln, bevor der Backend-Handler fertig ist.

Beispiel mit Prism:

npx @stoplight/prism-cli mock api/openapi.yaml

3. Vertragstests ausführen

Vertragstests prüfen, ob der laufende Server der Spezifikation entspricht. Wenn eine Response nicht zum Schema passt, schlägt CI fehl.

Das verhindert Spec/Code-Drift.

4. Dokumentation generieren

Referenzdokumentation sollte direkt aus der Spezifikation entstehen. So ändern sich Vertrag und Dokumentation im selben Workflow.

Das Prinzip bleibt gleich: Nicht manuell nachziehen. Aus der committeten Datei generieren.

Teamkonventionen, die skalieren

Ein Git-nativer Workflow funktioniert nur stabil, wenn das Team klare Konventionen hat.

1. Datei-Layout festlegen

Für kleine APIs reicht oft eine Datei:

api/openapi.yaml

Bei größeren APIs ist ein Split-Layout besser:

api/
  openapi.yaml
  paths/
    users.yaml
    invoices.yaml
  schemas/
    user.yaml
    invoice.yaml

Zur Build-Zeit bündeln Sie daraus eine einzelne Spezifikation.

2. Versionierung bewusst nutzen

Erhöhen Sie info.version bei relevanten Änderungen.

Faustregel:

• additive Änderung → Minor-Version
• Bugfix in Spezifikation → Patch-Version
• Breaking Change → Major-Version

Beispiel:

openapi: 3.1.0
info:
  title: Billing API
  version: 2.1.0

3. Changelog pflegen

Eine CHANGELOG.md neben der Spezifikation hilft Consumern besser als nur git log.

## 2.1.0

- Added `GET /users/{userId}/invoices`
- Added optional `status` query parameter
- Added `InvoiceList` response schema

4. CODEOWNERS verwenden

Schützen Sie Vertragsdateien mit verpflichtenden Reviews.

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

5. Linting in CI aktivieren

Ein Linter fängt Stil- und Konsistenzprobleme vor dem menschlichen Review ab.

# .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 CODEOWNERS plus CI-Linting bekommt jede Vertragsänderung automatische Checks und einen verantwortlichen Reviewer.

Häufige Fallstricke und Gegenmaßnahmen

Spec/Code-Drift

Problem: Die Spezifikation sagt etwas anderes als der laufende Server.

Gegenmaßnahme:

• Vertragstests in CI
• Server-Stubs oder Typen aus der Spezifikation generieren
• PRs blockieren, wenn Response-Schemas nicht passen

Riesige PRs

Problem: Ein PR ändert zwanzig Endpunkte. Reviewer überfliegen statt zu prüfen.

Gegenmaßnahme:

• ein Endpunkt oder eine logische Änderung pro PR
• Refactoring und semantische Änderung trennen
• Breaking Changes separat reviewen

Manuell gepflegte Artefakte

Problem: Clients, Mocks oder Dokumente werden händisch aktualisiert und driften.

Gegenmaßnahme:

• Clients generieren
• Mocks aus der Spezifikation starten
• Dokumentation aus OpenAPI rendern
• generierte Artefakte reproduzierbar machen

YAML-Merge-Konflikte

Problem: Langlebige Branches ändern dieselbe Datei.

Gegenmaßnahme:

• kurzlebige Branches
• stabile Schlüsselreihenfolge
• Split-File-Layout
• kleine PRs
• trunk-basiertes Arbeiten

Wo Apidog passt

Sie können diesen Workflow mit Editor, Git und CLI betreiben. Viele Teams möchten aber zusätzlich eine visuelle Designoberfläche, ohne Git als Single Source of Truth aufzugeben.

Dafür ist der Spec-First-Modus von Apidog gedacht. Die OpenAPI-Datei bleibt im Git-Repository, während Sie den Vertrag im visuellen Designer oder direkt im Editor bearbeiten. Beide Richtungen bleiben synchron. Die Datei in Git bleibt kanonisch, sodass Branches, Pull Requests und Historie weiterhin funktionieren.

Details zur Einrichtung finden Sie in der Spec-First Mode Dokumentation.

Der wichtige Punkt ist nicht das Tool, sondern die Disziplin: Das Repo bleibt die einzige Quelle der Wahrheit. Eine GUI ist nur eine Ansicht darauf.

FAQ

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

Nein. Der Workflow funktioniert mit jedem textbasierten Vertragsformat, z. B.:

• OpenAPI
• AsyncAPI
• gRPC-.proto
• GraphQL SDL

Wichtig ist nur: Der Vertrag ist diffbar, versionierbar und reviewbar.

Wie gehe ich mit Breaking Changes um?

Machen Sie Breaking Changes sichtbar:

1. Branch mit break/api- präfixen
2. Major-Version erhöhen
3. Review durch API-Stewards verlangen
4. Consumer informieren
5. Wenn möglich: alte und neue Form parallel anbieten
6. Alte Variante nach Zeitplan deprecaten

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

Meistens ja, wenn dasselbe Team Spezifikation und Implementierung besitzt. Dann kann ein PR Vertrag, Handler und Vertragstest zusammen ändern.

Ein separates Repo ist sinnvoll, wenn viele Teams dieselbe API konsumieren und die Spezifikation unabhängig versioniert werden muss.

Wie verhindere ich Drift zwischen Spezifikation und Code?

Kombinieren Sie drei Maßnahmen:

• generierte Typen, Clients oder Stubs
• Vertragstests gegen den laufenden Server
• CI-Checks bei jedem PR

So wird Drift zu einem Build-Fehler statt zu einem Produktionsproblem.

Fazit

Git-natives API-Design ist eine Arbeitsweise: Vertrag als Quellcode behandeln, Änderungen in Branches entwickeln, Pull Requests reviewen und nachgelagerte Artefakte aus der committeten Spezifikation generieren.

Starten Sie klein:

1. Spezifikation ins Repo verschieben
2. Linting in CI aktivieren
3. CODEOWNERS für API-Dateien einrichten
4. Vertragsänderungen nur per PR mergen
5. Danach Codegen, Mocks und Vertragstests ergänzen

Mit jeder Konvention wird der Workflow stabiler. Am Ende ist Ihre Git-Historie nicht nur Code-Historie, sondern eine vollständige Aufzeichnung der Entwicklung Ihrer API.