Frontend-Kompatibilität mit der API sicherstellen

Sie haben einen neuen Frontend-Build fertig. Das Team hat die Änderungen reviewed, die Tests bestanden, und das Bundle liegt bereit im CDN, um deployed zu werden. Doch bevor Sie den Schalter umlegen, gibt es eine Frage, die oft übersehen wird: Wird dieses Frontend noch mit der API funktionieren, die bereits in Produktion läuft?

Frontend und Backend werden selten gleichzeitig ausgeliefert. Die API bedient möglicherweise noch die alte Version, während Ihr Frontend einen neuen Endpunkt erwartet. Oder das API-Team hat gerade einen Breaking Change deployed, und Ihr Frontend wurde vor dieser Änderung gebaut. In beiden Fällen sehen die Nutzer kaputte Seiten, vermissen Daten oder bekommen stille Fehler, die niemand bemerkt, bis sich jemand beschwert.

Das ist kein Tool-Problem. Es ist ein Koordinationsproblem, das sich in Ihrer Pipeline zeigt.

Warum Frontend und API aus dem Takt geraten

Frontend und Backend haben grundlegend unterschiedliche Release-Rhythmen. Ein statisches Frontend im CDN kann sofort deployed werden. Kein Server-Neustart, kein Connection Drain, keine Migration. Sie schieben die Dateien hoch, und die nächste Benutzeranfrage holt sie ab.

Backend-APIs sind anders. Das Deployen einer neuen API-Version bedeutet oft, Anwendungsserver neu zu starten, Datenbankmigrationen durchzuführen oder die Infrastrukturkonfiguration zu aktualisieren. Das braucht Zeit und birgt eigene Risiken.

Wenn diese beiden Rhythmen nicht aufeinander abgestimmt sind, entsteht ein Zeitfenster, in dem das Frontend etwas erwartet und die API etwas anderes zurückgibt. Das Frontend ruft einen Endpunkt auf, der nicht mehr existiert. Oder die API beginnt, ein neues Feld auszuliefern, und das alte Frontend stürzt ab, weil es die Antwort nicht parsen kann.

Das Problem verschärft sich, wenn verschiedene Teams für Frontend und API verantwortlich sind. Das Frontend-Team weiß vielleicht nicht einmal, dass sich die API geändert hat, bis jemand einen Bug meldet.

API-Versionierung ist die klassische Antwort, aber sie hat ihren Preis

Die gängigste Lösung ist die Versionierung Ihrer API. Sie fügen ein Versionspräfix in die URL ein, wie /api/v1/orders und /api/v2/orders. Das alte Frontend ruft weiterhin v1 auf, während das neue Frontend auf v2 umsteigt. Beide Versionen leben nebeneinander, bis das alte Frontend vollständig ausgemustert ist.

Das funktioniert, ist aber nicht kostenlos. Die Wartung mehrerer API-Versionen bedeutet technische Schulden für Ihr Backend-Team. Jede neue Funktion muss in beiden Versionen implementiert werden, oder Sie müssen einen Deprecation-Zeitplan erstellen. Die Nutzer müssen irgendwann migrieren, und diese Migration ist selbst ein Projekt.

Versionierung ist ein Sicherheitsnetz, aber ein schweres. Für Teams, die häufig ausliefern, wird die Wartung von zwei oder drei API-Versionen zu einer Bremse für die Geschwindigkeit.

Feature Flags geben Ihnen mehr Kontrolle

Ein flexiblerer Ansatz sind Feature Flags. Sie liefern das neue Frontend mit den neuen API-Aufrufen bereits im Bundle aus, aber diese Aufrufe sind hinter einem Flag versteckt, das deaktiviert ist. Die Nutzer laden das neue Frontend herunter, erreichen aber nie den neuen Endpunkt, weil die Funktion inaktiv ist.

Wenn das API-Team sein Deployment abgeschlossen hat, schalten Sie das Flag über ein Dashboard um. Das Frontend beginnt, den neuen Endpunkt aufzurufen, ohne dass ein erneuter Download nötig ist. Kein App-Store-Review, kein CDN-Cache-Purge, kein Koordinationsmeeting.

Feature Flags sind besonders nützlich, wenn Frontend und API von verschiedenen Teams entwickelt werden. Das Frontend-Team kann nach seinem Zeitplan ausliefern, das API-Team nach seinem. Das Flag wird zum einzigen Koordinationspunkt.

Der Nachteil ist, dass Sie Code ausliefern, der noch nicht aktiv ist. Dieser Code ist getestet und reviewed, liegt aber untätig im Browser des Nutzers. Wenn Ihre Bundle-Größe eine Rolle spielt, müssen Sie vorsichtig sein, wie viel toten Code Sie ausliefern.

Vertragstests erkennen Probleme vor dem Release

Feature Flags und Versionierung kümmern sich um das Koordinationsproblem im Nachhinein. Sie können Inkompatibilitäten aber auch erkennen, bevor das Frontend überhaupt in Produktion geht. Der Mechanismus dafür sind Vertragstests in Ihrer CI/CD-Pipeline.

So funktioniert es: Während des Frontend-Builds führt Ihre Pipeline eine Reihe von Vertragstests durch. Diese Tests prüfen, ob die API-Antworten, die Ihr Frontend erwartet, mit den tatsächlichen Antworten der API übereinstimmen. Wenn die API ein Feld zurückgibt, das das Frontend nicht erwartet, oder wenn ein Feld fehlt oder sich der Datentyp geändert hat, schlägt der Vertragstest fehl und die Pipeline stoppt.

So sieht ein minimaler Vertragstest in der Praxis aus:

// contract-test.js - run in CI before deploying frontend
async function checkUserEndpoint() {
  const response = await fetch('https://api.example.com/v1/users/1');
  const data = await response.json();

  // Assert the shape the frontend expects
  if (typeof data.id !== 'number') {
    throw new Error('Expected id to be a number');
  }
  if (typeof data.name !== 'string') {
    throw new Error('Expected name to be a string');
  }
  if (!Array.isArray(data.roles)) {
    throw new Error('Expected roles to be an array');
  }

  console.log('Contract test passed: /users/:id matches frontend expectations');
}

checkUserEndpoint().catch(err => {
  console.error('Contract test failed:', err.message);
  process.exit(1);
});

Dieser Test läuft gegen die Live-API im Staging oder in der Produktion. Wenn die API einen Feldtyp ändert oder ein erforderliches Feld entfernt, schlägt die Pipeline fehl, bevor das Frontend die Nutzer erreicht.

Sie führen diese Vertragstests gegen die Version der API aus, die gerade im Staging oder in der Produktion läuft – je nach Ihrer Strategie. Der Test prüft nicht die Geschäftslogik. Er prüft nur die Struktur: Enthält die Antwort die Felder, die das Frontend braucht, und haben sie die richtigen Typen?

Vertragstests ersetzen keine Integrationstests. Integrationstests verifizieren, dass das gesamte System korrekt funktioniert. Vertragstests verifizieren nur, dass Frontend und API miteinander kommunizieren können, ohne abzustürzen. Aber für Kompatibilitätsprobleme sind Vertragstests genau das Richtige. Sie sind schnell, laufen in jeder Pipeline und fangen die häufigste Klasse von Frontend-Backend-Diskrepanzen ab.

Kombinieren Sie diese Ansätze für ein praktisches Sicherheitsnetz

Keine einzelne Technik deckt jedes Szenario ab. API-Versionierung bewältigt die langfristige Koexistenz. Feature Flags bewältigen zeitliche Verschiebungen beim Release. Vertragstests erkennen Probleme, bevor sie die Nutzer erreichen.

Das folgende Flussdiagramm hilft Ihnen bei der Entscheidung, welcher Ansatz für Ihre Situation geeignet ist:

flowchart TD A[Frontend und API nicht synchron?] --> B{Handelt es sich um einen großen Breaking Change?} B -->|Ja| C[API-Versionierung verwenden] B -->|Nein| D{Ist das Backend noch nicht bereit?} D -->|Ja| E[Feature Flags verwenden] D -->|Nein| F{Müssen Sie Diskrepanzen vor dem Release erkennen?} F -->|Ja| G[Vertragstests in CI einbauen] F -->|Nein| H[Keine Aktion nötig] C --> I[Deprecation-Zeitplan erstellen] E --> J[Frontend-Code inaktiv ausliefern, Flag später umschalten] G --> K[Pipeline schlägt bei Strukturkonflikt fehl] I --> L[Kombinieren mit Flags und Tests für vollständiges Sicherheitsnetz] J --> L K --> L

Ein praktisches Setup sieht so aus:

  • Verwenden Sie API-Versionierung für große Breaking Changes, die viele Konsumenten betreffen.
  • Verwenden Sie Feature Flags für die Koordination auf Feature-Ebene zwischen Frontend- und Backend-Teams.
  • Bauen Sie Vertragstests in Ihre Frontend-Pipeline als Gate ein, das inkompatible Builds am Deployment hindert.

Diese Kombination gibt Ihnen mehrere Schutzschichten, ohne jedes Team zu zwingen, denselben Release-Zeitplan einzuhalten.

Eine kurze Checkliste für Ihre Pipeline

Wenn Sie zum ersten Mal Kompatibilitätsprüfungen einrichten, finden Sie hier eine kurze Liste für den Einstieg:

  • Identifizieren Sie, von welchen API-Endpunkten Ihr Frontend abhängt.
  • Schreiben Sie Vertragstests, die die Struktur jeder Antwort prüfen.
  • Führen Sie diese Tests in Ihrer Frontend-CI-Pipeline gegen die aktuelle Staging- oder Produktions-API aus.
  • Konfigurieren Sie die Pipeline so, dass sie bei einem fehlgeschlagenen Vertragstest abbricht.
  • Für Features, die im Backend noch nicht bereit sind, kapseln Sie die Frontend-Aufrufe in ein Feature Flag.
  • Planen Sie einen Deprecation-Zeitplan für alte API-Versionen und kommunizieren Sie diesen an alle Frontend-Teams.

Worauf es ankommt

Frontend-Backend-Kompatibilität ist keine technische Neuheit. Es ist eine alltägliche Realität für jedes Team, das Frontend-Code gegen eine Live-API ausliefert. Das Risiko ist nicht, dass Ihr Code Fehler hat. Das Risiko ist, dass Ihr Code korrekt ist, aber mit der falschen Version der API spricht.

Versionierung, Feature Flags und Vertragstests lösen jeweils einen anderen Teil dieses Problems. Setzen Sie sie gemeinsam ein, und Ihre Pipeline wird zu einem zuverlässigen Gate, das inkompatiblen Code von den Nutzern fernhält.