API-First: Workflow zwischen Backend, Frontend und QA

1. Das Problem ohne API-First: Blockaden im Teamworkflow

In den meisten Teams läuft API-Entwicklung in einer bestimmten Reihenfolge ab: Das Backend-Team implementiert Endpoints, schickt dem Frontend-Team die fertige URL und einen Screenshot der JSON-Antwort, und QA wartet, bis beide fertig sind, um manuelle Tests auszuführen. Dieses Modell hat einen fundamentalen Schwachpunkt: Jede Abhängigkeit erzeugt eine Blockade. Das Frontend kann nicht mit der Arbeit beginnen, solange der Endpoint nicht live ist. QA kann nicht testen, solange Frontend nicht integriert hat. Backend muss unterbrechend auf jede Rückfrage reagieren.

Was auf dem Papier wie ein sequenzieller Workflow aussieht, fühlt sich in der Praxis wie ein permanentes Warten an. Hinzu kommen Missverständnisse: Der Feldname, den das Frontend erwartet, heißt im Backend anders. Der Fehlercode, den QA testet, stimmt nicht mit dem überein, den Backend zurückgibt. Das Nullable-Feld, das Frontend behandelt, kann Backend in einer Randbedingung tatsächlich als leer zurückgeben – und dieser Fall ist im Code nirgendwo dokumentiert. API-First löst dieses strukturelle Problem, indem die Schnittstelle als erstes Artefakt des Entwicklungszyklus entsteht – nicht als letztes.

2. Was API-First konkret bedeutet – und was nicht

API-First bedeutet: Die Spezifikation wird vor dem Code geschrieben. Sie ist kein nachträgliches Dokumentationsdokument, sondern das Designartefakt, aus dem alle anderen Aktivitäten folgen. OpenAPI 3.1 ist der Industriestandard für diese Spezifikation – ein YAML- oder JSON-Dokument, das Endpoints, Request-Bodies, Response-Schemas, Status-Codes, Sicherheitsanforderungen und Beispiele vollständig beschreibt. Dieses Dokument lebt im Repository, wird versioniert und ist die vertragliche Grundlage für alle Teams.

Was API-First nicht bedeutet: Es ist kein Wasserfall-Prozess, bei dem wochenlang ein Mega-Dokument spezifiziert wird, bevor eine einzige Zeile Code entsteht. In der Praxis bedeutet API-First, dass jede User Story oder jedes Feature zuerst auf Schnittstellenebene diskutiert und spezifiziert wird – auch wenn das nur ein einziger neuer Endpoint oder ein erweitertes Schema ist. Die Spezifikation wird iterativ erweitert, nicht auf einmal vollständig erstellt. Der Unterschied zum Code-First-Ansatz liegt nicht in der Menge des upfront-Designs, sondern darin, dass die Schnittstelle explizit entworfen wird, bevor Implementierungsentscheidungen sie implizit formen.

3. Die OpenAPI-Spezifikation gemeinsam erarbeiten

Die Erarbeitung der Spezifikation ist ein kollaborativer Prozess, der alle betroffenen Teams einbezieht. Backend-Entwickler verstehen, was technisch umsetzbar ist und welche Daten die Datenbank liefern kann. Frontend-Entwickler wissen, welche Datenstruktur ihre Komponenten benötigen und welche Felder in welchem Kontext dargestellt werden. Product Owner kennen die fachlichen Anforderungen. QA-Ingenieure identifizieren Randbedingungen und Fehlerfälle, die in der Spezifikation abgedeckt sein müssen.

Das Ergebnis ist eine OpenAPI-Datei, die im Git-Repository unter api/openapi.yaml versioniert wird. Jede Änderung an der Spezifikation durchläuft denselben Pull-Request-Prozess wie Code. API-Lint-Tools wie spectral prüfen die Spezifikation automatisch auf Konsistenz, fehlende Beispiele und Konventionsverletzungen. Die Spezifikation enthält nicht nur die Happy-Path-Antworten, sondern explizit alle Fehlerfälle mit Status-Codes und Fehlerschemas – denn genau diese sind es, die im Teamalltag die meisten Missverständnisse erzeugen.

# api/openapi.yaml — excerpt: user endpoint with full error coverage
openapi: "3.1.0"
info:
  title: Mironsoft API
  version: "2.0.0"

paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Retrieve a single user by ID
      tags: [Users]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1 }
          example: 42
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserResponse" }
              examples:
                active_user:
                  summary: Active user with all fields
                  value:
                    id: 42
                    email: "user@example.com"
                    name: "Maria Mustermann"
                    role: "editor"
                    active: true
                    createdAt: "2025-01-15T10:30:00Z"
        "404":
          description: User not found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
              example:
                code: "USER_NOT_FOUND"
                message: "No user with ID 42 found"
        "401":
          $ref: "#/components/responses/Unauthorized"

components:
  schemas:
    UserResponse:
      type: object
      required: [id, email, name, role, active, createdAt]
      properties:
        id:     { type: integer }
        email:  { type: string, format: email }
        name:   { type: string, maxLength: 255 }
        role:   { type: string, enum: [admin, editor, viewer] }
        active: { type: boolean }
        createdAt: { type: string, format: date-time }
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:    { type: string }
        message: { type: string }

4. Backend: Code gegen Spezifikation entwickeln

Das Backend-Team beginnt die Implementierung mit der fertig abgenommenen Spezifikation als Vertrag. Für PHP-Projekte bieten sich Tools wie openapi-generator an, die aus der Spezifikation Server-Stubs erzeugen – konkrete Interface-Klassen, die das Backend implementieren muss. Das stellt sicher, dass Endpoint-Signaturen, Parameternamen und Response-Strukturen exakt der Spezifikation entsprechen, nicht einer subjektiven Interpretation davon.

Zusätzlich validiert eine Middleware bei jedem Request und bei jeder Response, ob die tatsächlichen Daten dem Schema der Spezifikation entsprechen. In Symfony bietet league/openapi-psr7-validator diese Validierung als Middleware-Schicht. Das bedeutet: Weicht die Backend-Implementierung von der Spezifikation ab, schlägt die Validierung fehl – nicht erst in QA, nicht erst beim Frontend-Team, sondern sofort beim Entwickeln. Der Vertrag wird automatisch durchgesetzt, nicht durch Reviews allein.

# Generate PHP server interfaces from OpenAPI spec
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g php-symfony \
  -o src/Generated/Api \
  --additional-properties=invokerPackage=App\\Generated

# Lint OpenAPI spec with Spectral (CI step)
npx @stoplight/spectral-cli lint api/openapi.yaml \
  --ruleset .spectral.yaml \
  --format junit \
  --output .reports/spectral.xml

# Validate generated PHP interfaces match spec
composer validate-api
# Runs: vendor/bin/openapi-spec-validator api/openapi.yaml

# Run backend tests with request/response validation middleware active
composer test -- --group api-contract

5. Frontend: Mit Mocks parallel entwickeln

Sobald die OpenAPI-Spezifikation mit vollständigen Beispielen im Repository liegt, kann das Frontend-Team mit der Entwicklung beginnen – ohne auf das Backend zu warten. Ein Mock-Server wie Prism von Stoplight liest die Spezifikation und serviert automatisch die darin definierten Beispiele als echte HTTP-Antworten. Der Frontend-Entwickler konfiguriert die API-Basis-URL auf den lokalen Mock-Server und entwickelt Komponenten gegen reale Daten, die exakt der Spezifikation entsprechen.

Dieser Ansatz hat einen entscheidenden Vorteil gegenüber fest kodierten Fixtures im Frontend-Code: Die Mock-Daten sind dieselben Daten, die im Vertrag stehen. Wenn Backend später eine Antwortstruktur ändert und der Vertrag angepasst wird, aktualisiert der Mock automatisch, und das Frontend-Team sieht sofort, welche Komponenten angepasst werden müssen – noch bevor das Backend-Feature fertig ist. Die parallele Entwicklung läuft in dieser Konfiguration ohne Abhängigkeiten.

# Start Prism mock server from OpenAPI spec (Frontend dev)
npx @stoplight/prism-cli mock api/openapi.yaml \
  --port 4010 \
  --dynamic           # generate dynamic fake data when no example exists

# Frontend connects to mock: http://localhost:4010/users/42
# Returns the example defined in openapi.yaml exactly

# Validate that mock responses match schema (CI smoke test)
npx @stoplight/prism-cli proxy api/openapi.yaml http://localhost:8080 \
  --port 4011 \
  --errors            # return 422 on schema violations instead of passing through

# TypeScript client generation from spec (keeps types in sync)
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o frontend/src/api/generated \
  --additional-properties=supportsES6=true,typescriptThreePlus=true

6. QA: Contract-Tests automatisch aus der Spec ableiten

QA-Teams profitieren von API-First am direktesten: Statt manuell zu prüfen, ob ein Endpoint die dokumentierte Antwort liefert, werden Contract-Tests automatisch aus der Spezifikation generiert. Tools wie schemathesis lesen die OpenAPI-Spezifikation und generieren systematisch Testfälle – für alle definierten Beispiele, für Boundary-Werte bei Zahlen und Strings, für fehlende Pflichtfelder und für ungültige Typen. Statt 20 manuell geschriebener Testfälle entstehen automatisch Hunderte von Tests, die exakt den Vertrag abdecken.

Für strukturiertere Contract-Tests schreibt QA zusätzlich explizite Tests gegen die Spezifikation. Jeder Test ruft einen echten Endpoint auf und validiert die Antwort gegen das JSON-Schema aus der Spezifikation. Das Testframework muss dafür keinen Vertrag kennen – es reicht, die Spezifikation zu laden und die Validierungsbibliothek anzusprechen. QA validiert nicht, was implementiert ist, sondern was vereinbart wurde – ein fundamentaler Unterschied für die Fehlerrate in der Integration.

7. API-Design-Review: Wie strukturierte Governance funktioniert

In wachsenden Teams entstehen schnell inkonsistente APIs: Ein Team nutzt camelCase für Felder, ein anderes snake_case. Ein Endpoint gibt Fehler als {"error": "…"} zurück, ein anderer als {"message": "…", "code": 42}. Versionierung wird einmal im URL-Pfad, einmal als Header-Wert kodiert. Diese Inkonsistenzen entstehen nicht aus Fahrlässigkeit, sondern aus fehlendem Governance-Prozess. API-Design-Reviews sind der strukturelle Antwort darauf.

Ein effektiver Review-Prozess für API-First-Teams enthält drei Ebenen: Automatische Prüfung durch Lint-Rules, die in der CI-Pipeline laufen und technische Konventionen durchsetzen; Peer-Review durch ein anderes Team-Mitglied, das die fachliche Vollständigkeit und Verständlichkeit beurteilt; und optionale Architektur-Review durch einen API-Guild oder einen Designated API-Owner für teamübergreifende Konsistenz. Nur die erste Ebene ist immer Pflicht – die anderen skalieren mit der Teamgröße und dem Risiko des betroffenen Endpoints.

# .spectral.yaml — Custom API governance rules
extends: ["spectral:oas"]

rules:
  # All operations must have operationId
  operation-operationId-required:
    message: "Every operation needs an operationId for code generation"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: error
    then:
      field: operationId
      function: truthy

  # Enforce camelCase field names
  schema-properties-camelCase:
    message: "Schema properties must use camelCase naming"
    given: "$.components.schemas[*].properties"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  # All error responses need the standard ErrorResponse schema
  error-response-schema:
    message: "4xx/5xx responses must reference ErrorResponse schema"
    given: "$.paths[*][*].responses[4xx,5xx].content.application/json.schema"
    severity: warn
    then:
      function: schema
      functionOptions:
        schema:
          properties:
            $ref: { type: string, pattern: "ErrorResponse" }

  # Require examples for all response schemas
  response-examples-required:
    message: "All 2xx responses need at least one example"
    given: "$.paths[*][*].responses[2xx].content.application/json"
    severity: warn
    then:
      field: examples
      function: truthy

8. API-First vs. Code-First: Direkter Vergleich

Die Wahl zwischen API-First und Code-First ist keine technische, sondern eine prozessuale Entscheidung mit messbaren Auswirkungen auf die Teamgeschwindigkeit und die Qualität der Integration. Der direkte Vergleich zeigt, wo die entscheidenden Unterschiede liegen – nicht nur in der Dokumentation, sondern im gesamten Entwicklungszyklus.

Die Tabelle zeigt den strukturellen Vorteil von API-First: Jede Investition in die Spezifikationsqualität zahlt sich dreifach aus – für Backend, Frontend und QA. Der einzige echte Mehraufwand gegenüber Code-First liegt im Design-Review-Prozess und in der initialen Disziplin, die Spezifikation vor dem Code zu schreiben. Dieser Aufwand amortisiert sich typischerweise ab dem ersten Feature, das parallel von mehreren Teams entwickelt wird.

9. Zusammenfassung

API-First ist kein Dokumentationsprojekt, sondern ein Prozessmuster, das parallele Entwicklung im Team ermöglicht. Die OpenAPI-Spezifikation entsteht zuerst, wird als Vertrag zwischen Backend, Frontend und QA behandelt und liegt versioniert im Repository. Backend implementiert gegen diesen Vertrag, Frontend entwickelt mit Mock-Servern parallel, QA leitet Contract-Tests automatisch aus der Spezifikation ab. Lint-Tools erzwingen technische Konventionen, Design-Reviews sichern fachliche Qualität.

Der messbare Effekt: Weniger Integrationsbugs, weniger Rückfragen zwischen Teams und eine Dokumentation, die immer aktuell ist, weil sie das Entwicklungsartefakt ist – nicht ein nachträglicher Aufwand. Teams, die API-First einführen, berichten regelmäßig von kürzeren Integrationszyklen und weniger überraschenden Regressionen in der letzten Phase vor dem Release.

10. FAQ: API-First Teams-Workflow