9 API-Änderungen, die Ihre App zum Absturz bringen

„Wir haben nichts kaputt gemacht. Wir haben nur die Antwort aufgeräumt.“

Diese Worte führen oft zu Abstürzen. Eine mobile App versagt. Eine Partner-Integration liefert Müll zurück. Sie haben die Struktur von Daten geändert, auf die andere angewiesen sind.

Gefährliche Änderungen sehen oft nach Aufräumarbeiten aus. Sie bestehen Code-Reviews und Tests. Der Bruch geschieht in Code, den Sie nicht sehen können.

Hier sind neun Änderungen, die sich sicher anfühlen, es aber nicht tun.

• Umbenennen von Feldern Das Ändern von userId zu user_id aus Gründen der Konsistenz bricht Clients. Eine Umbenennung ist ein Löschen und ein Hinzufügen. Der Löschvorgang verursacht Fehler bei den Nutzern. Sicherer Weg: Fügen Sie das neue Feld hinzu. Behalten Sie das alte bei. Markieren Sie es als veraltet (Deprecation). Entfernen Sie es erst viel später.

• Ein Feld optional machen Ein Feld war früher immer vorhanden. Jetzt ist es manchmal null. Der Client-Code stürzt ab, wenn er versucht, es zu verarbeiten. Sicherer Weg: Betrachten Sie „immer vorhanden“ als ein Versprechen. Wenn ein Feld optional wird, verwenden Sie eine neue Version.

• Unbenutzte Felder entfernen Sie können nicht sehen, wie Ihre Konsumenten Ihre Daten nutzen. „Unbenutzt“ bedeutet nur, dass sie von Ihnen nicht genutzt werden. Sicherer Weg: Messen Sie die Feldernutzung in der Produktion, bevor Sie etwas entfernen.

• Eingabetypen einschränken Das Ändern eines string in ein enum oder einer Zahl in einen integer bricht Anfragen. Die Erweiterung einer Eingabe ist sicher. Die Einschränkung ist eine Breaking Change. Sicherer Weg: Lockern Sie nur die Eingaben auf, die Sie akzeptieren. Eine Verschärfung erfordert eine neue Version.

• Standardwerte ändern Das Ändern eines Standardwerts von false zu true ändert das Verhalten ohne Fehlermeldung. Dies bricht die Logik stillschweigend. Sicherer Weg: Behandeln Sie eine Änderung des Standardwerts wie eine Breaking Change.

• Erforderliche Felder hinzufügen Das Hinzufügen von tenantId und das Festlegen als erforderlich bricht jeden bestehenden Client. Sie erhalten einen 400-Fehler. Sicherer Weg: Neue Felder müssen optional sein oder eine neue Version erfordern.

• Fehlerformate ändern Das Ändern eines 400-Fehlers in einen 422-Fehler oder das Ändern des Error-Bodys bricht den Code zur Fehlerbehandlung. Sicherer Weg: Fehlerformate sind Verträge. Versionieren Sie diese wie alles andere auch.

• Enum-Werte modifizieren Das Umbenennen von „active“ in „ACTIVE“ bricht Clients. Das Entfernen eines Wertes bricht Clients mit strikter Logik. Sicherer Weg: Enum-Werte sind für immer. Fügen Sie sie vorsichtig hinzu. Benennen Sie sie niemals um oder entfernen Sie sie ohne eine neue Major-Version.

• Die Bedeutung von Daten ändern Das Ändern eines Datums von Unix-Sekunden zu ISO-8601 oder das Ändern der Paginierung von Offset auf Cursor bricht alles. Ein Schema-Diff erkennt dies möglicherweise nicht einmal. Sicherer Weg: Legen Sie Formate explizit fest. Vergleichen Sie echte Payloads, nicht nur die Spezifikation.

Verlassen Sie sich nicht auf Ihr Bauchgefühl. Vergleichen Sie jede Änderung in Ihrer CI mit dem Production Contract. Ein Mensch übersieht vielleicht ein umbenanntes Feld. Ein Diff-Tool hingegen nicht.

Quelle: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0