API-Änderungen mit JSON Diff prüfen

Nach dem API-Upgrade von v1 auf v2: Welche Felder sind neu in der JSON-Antwort? Gibt es Breaking Changes? Bei 500 Zeilen Response und Zeile-für-Zeile-Vergleich übersehen Sie leicht Änderungen tief in verschachtelten Objekten.

Dieser Artikel richtet sich an Frontend-, Backend- und Test-Ingenieure, erklärt Prinzipien von JSON Diff, Anwendungsfälle, einen 5-Schritte-Workflow sowie Fallstricke wie Array-Reihenfolge und Gleitkomma-Genauigkeit. Danach können Sie mit der Diff-Funktion der JSON-Toolbox lokal im Browser eine vollständige API-Änderungsprüfung durchführen — ohne Upload.

Warum nach API-Upgrades JSON Diff Pflicht ist

In Microservices und Frontend/Backend-Trennung ist der API-Vertrag (Contract) die Basis der Zusammenarbeit. Ein scheinbar „abwärtskompatibles“ Upgrade kann Felder still entfernen, Array-Strukturen ändern oder Strings in Zahlen wandeln — Clients merken es erst in Produktion.

Aus dem Alltag: Eine User-List-API v2 änderte pagination.total von number zu string — alte Mobile-Clients crashten mit White Screen. Hätte man vor dem Release v1/v2-Beispielantworten mit JSON Diff verglichen, wäre der Typwechsel in Sekunden markiert.

Was ist JSON Diff

JSON Diff vergleicht zwei JSON-Dokumente strukturiert und hebt hinzugefügte (added), gelöschte (removed) und geänderte (modified) Felder hervor. Anders als Text-Diff versteht es JSON-Hierarchie und ignoriert reine Einrückungs-/Zeilenumbruch-Unterschiede.

Kernunterschied zum Text-Diff

Diff-Ergebnisse lesen

• Grün / hinzugefügt: Feld nur in der rechten JSON
• Rot / gelöscht: Feld nur in der linken JSON
• Gelb / geändert: Gleicher Pfad, anderer Wert
• Keine Hervorhebung: Struktur identisch

Für wen JSON Diff geeignet ist

Typische Anwendungsfälle

• API-Version-Regression: v1 vs. v2 Response-Struktur
• Config-Audit: JSON vor und nach Deployment
• ETL / Migration: Skript-Output vs. Erwartung
• Code Review: große JSON-fixture schnell überfliegen

Praxis: 5 Schritte zur API-Änderungsprüfung

Workflow mit dem JSON-Toolbox Diff-Tool — lokal im Browser, auch für interne Beispiele (token, Passwörter vorher entfernen).

1. Alte Antwort sichern: Beispiel aus v1 oder Doku als baseline.json
2. Neue Antwort holen: v2-API oder aktualisierte mock-Daten
3. Optional formatieren: Beide Seiten schön formatieren, Whitespace-Rauschen vermeiden
4. Diff ausführen: Beide JSONs links/rechts einfügen, „Vergleich starten“
5. Unterschiede dokumentieren: Markierte Punkte prüfen, in CHANGELOG oder Tests

Beispiel: zwei User-API-Antworten

JSON A (v1, alt):

{
  "name": "Alice",
  "age": 30,
  "tags": ["dev", "json"],
  "profile": {
    "city": "Shanghai",
    "level": "senior"
  }
}

JSON B (v2, neu):

{
  "name": "Alice",
  "age": 31,
  "tags": ["dev", "tools"],
  "active": true,
  "profile": {
    "city": "Beijing",
    "level": "senior"
  }
}

Der Diff markiert: age 30 → 31; tags-Inhalt geändert; profile.city Shanghai → Beijing; active neu. Fehlt das im Release-Note, drohen Client-Kompatibilitätsprobleme.

Tipps und typische Fallstricke

Erst formatieren, dann vergleichen

Eine Seite minified, die andere mehrzeilig — Text-Diff erzeugt Rauschen. Beide formatieren, dann nur semantische Änderungen betrachten.

Array-Reihenfolge ≠ Inhaltsänderung

Gleicher Inhalt, andere Reihenfolge — JSON Diff kann viele Änderungen zeigen. Geschäftlich klären: Ist das Array geordnet (Timeline) oder nur eine Menge?

Gleitkomma und Typen

• 1.0 vs. 1.000 kann als Änderung gelten — ggf. normalisieren
• String "123" vs. Zahl 123 — unterschiedliche Typen, oft Breaking Change
• null vs. fehlendes Feld — unterschiedliche Semantik, Diff trennt beides

Sensible Daten entfernen

Vor dem Vergleich access_token, password, IDs durch Platzhalter (z. B. "***") ersetzen. JSON-Toolbox läuft rein frontend — Entfernen bleibt gute Praxis.

JSON Diff im Vergleich zu anderen Methoden

Best Practice: In Dev JSON Diff für schnelle Reviews → wichtige Unterschiede in automatisierte Tests → vor Major-Releases JSON Schema für Struktur. Ergänzen sich, ersetzen sich nicht.

Häufige Fragen (FAQ)

Fazit und nächste Schritte

Nach API-Upgrade, Config-Migration oder Datensync ist JSON Diff eines der effizientesten Mittel gegen „stille“ Breaking Changes. Kernpunkte: formatieren → farbige Markierungen prüfen → in Changelog oder Tests festhalten.

Frontend/Test: baseline beim Debugging speichern, nach Upgrade direkt Diff. Backend: in PR-Templates v1/v2-Diff-Screenshot als Release-Gate verlangen.