Beim Entwerfen von APIs ist eine der größten Herausforderungen für Entwickler sicherzustellen, dass zukünftige Änderungen bestehende Client-Implementierungen nicht beeinträchtigen. Zu oft haben wir gut gemeinte Clients gesehen, die JSON-Antworten auf starre Weise analysieren, Feldpositionen hart kodieren oder Annahmen über die Struktur der Antwort treffen, die später die API-Entwicklung verhindern.
Deshalb haben wir uns entschieden, zufällige Felder zu unseren JSON-API-Antworten hinzuzufügen – ein proaktiver Ansatz, inspiriert von erfolgreichen Implementierungen von Chrome und Let's Encrypt.
Das Problem: Rigide Client-Implementierungen
JSON-APIs sind darauf ausgelegt, erweiterbar zu sein. Die JSON-Spezifikation unterstützt von Natur aus das Hinzufügen neuer Felder, ohne bestehende Parser zu beeinträchtigen. Die Realität ist jedoch komplexer. Viele Client-Entwickler, sei es aus Zeitmangel, Unerfahrenheit oder Missverständnissen, erstellen Implementierungen, die gegenüber Änderungen intolerant sind.
Häufige problematische Muster umfassen:
- Hartkodierung von Array-Indizes anstelle der Verwendung von Feldnamen
- Ablehnen von Antworten, die unbekannte Felder enthalten
- Annahmen über die Reihenfolge der Felder treffen
- Zu strikte Validierung implementieren, die bei neuen Eigenschaften fehlschlägt
Diese Implementierungsentscheidungen schaffen eine erhebliche Belastung für API-Pflegende. Jedes neue Feld oder jede Verbesserung birgt das Potenzial für breaking changes, was Innovation erstickt und die natürliche Entwicklung der API verhindert.
Lernen von den Experten
Unser Ansatz wurde inspiriert von zwei bemerkenswerten Beispielen in der Tech-Branche:
Chromes TLS-Erweiterungs-Randomisierung
Chrome implementierte die Permutation der TLS ClientHello-Erweiterungen, um zu verhindern, dass Server eine bestimmte feste Reihenfolge von Erweiterungen erwarten, die Chrome daran hindern könnte, zukünftige Änderungen an seiner TLS-Implementierung vorzunehmen. Durch die zufällige Reihenfolge der TLS-Erweiterungen stellte Chrome sicher, dass Server-Implementierungen sich nicht auf bestimmte Reihenfolgen verlassen konnten, wodurch das gesamte TLS-Ökosystem robuster gegenüber zukünftigen Änderungen wurde.
Let's Encrypt's Directory Randomisierung
Let's Encrypt fügte Schlüssel mit zufällig generierten Namen zu ihrem Verzeichnis-Endpunkt hinzu, um Entwickler davon abzuhalten, Clients so zu schreiben, dass sie das Hinzufügen neuer Schlüssel in Zukunft verhindern. Diese proaktive Maßnahme adressierte die Herausforderung, die sie mit frühen ACME-Clients hatten, die gegenüber neuen Feldern intolerant waren, was es schwierig machte, neue Funktionalitäten einzuführen.
Beide Ansätze teilen eine gemeinsame Philosophie: Variabilität früh einführen, um die Verfestigung des Client-Verhaltens zu verhindern.
Unsere Implementierungsstrategie
Nach diesen Beispielen implementieren wir die Zufallseinfeld-Injektion in unseren JSON-API-Antworten. So funktioniert es:
Generierung zufälliger Felder
{
"success": true,
"result": {
"email": "user@gentlent.com",
"i5dgf3": "https://gentl.net/random-api",
"id": "1647603024929000000",
"profile_img": "https://www.gravatar.com/avatar/4584d61ab0bef9513f93a273ac985488?r=pg&d=identicon&s=128",
"reseller_id": "12",
"support_plan": "basic",
"username": "user"
}
}Schlüsseleigenschaften
- Zufällige Feldnamen: Jede Antwort enthält 1-2 Felder mit zufällig generierten Namen
- Vorhersehbare Werte: Die Feldwerte verweisen auf Dokumentationen, die den Zweck erklären
- Verschachteltes Einfügen: Zufällige Felder erscheinen sowohl auf der Wurzelebene als auch innerhalb verschachtelter Objekte
- Dokumentationslinks: Feldwerte verweisen auf unsere API-Erweiterungsrichtlinien
Implementierungsrichtlinien
- Feldnamen folgen dem Muster: randomField_[5-Zeichen-String] oder randomProperty_[5-Zeichen-String]
- Werte verlinken immer zu unserer Dokumentation, um Entwicklern zu helfen, den Zweck zu verstehen
- Zufallsfelder werden serverseitig für jede Antwort generiert
- Felder werden auf verschiedenen Verschachtelungsebenen eingefügt, um umfassendes Parsen zu testen
Vorteile für die langfristige API-Gesundheit
Dieser Ansatz bietet mehrere wesentliche Vorteile:
Unmittelbares Feedback: Clients, die bei unbekannten Feldern ausfallen, scheitern sofort während der Entwicklung, nicht Monate später, wenn wir neue Funktionen einführen.
Entwicklerbildung: Die Dokumentationslinks in zufälligen Feldwerten helfen, den Entwicklern zu zeigen, wie man JSON korrekt analysiert.
Widerstandsfähigkeit des Ökosystems: Durch die Normalisierung der Präsenz unbekannter Felder schaffen wir ein widerstandsfähigeres Ökosystem, das sich an zukünftige Änderungen anpassen kann.
Reduzierte breaking changes: Künftige API-Verbesserungen werden additiv anstatt zerbrechlich, was die Versionskomplexität reduziert.
Implementierungsumfang
Derzeit betrifft diese Randomisierung nur unsere JSON-Objektantworten. Andere API-Formate und -Endpunkte bleiben unverändert, während wir die Effektivität dieses Ansatzes bewerten. Wir überwachen das Feedback der Client-Entwickler und erweitern die Implementierung basierend auf den Ergebnissen.
Best Practices für Client-Entwickler
Wenn Sie Clients entwickeln, die unsere APIs nutzen, sind hier die empfohlenen Ansätze:
✅ Machen Sie:
- Analysieren Sie JSON-Antworten unter Verwendung von Feldnamen, nicht Positionen
- Ignorieren Sie unbekannte Felder elegant
- Verwenden Sie geeignete JSON-Parsing-Bibliotheken, die Erweiterbarkeit unterstützen
- Implementieren Sie eine flexible Antwortbehandlung
❌ Nicht machen:
- Hartkodierung von Feldpositionen oder Array-Indizes
- Ablehnung von Antworten, die unbekannte Eigenschaften enthalten
- Annahmen über die Reihenfolge der Felder treffen
- Implementierung strikter Validierungen, die bei neuen Feldern fehlschlägt
Blick in die Zukunft
Diese Änderung stellt unser Engagement für den Aufbau von APIs dar, die über die Zeit hinweg sich anpassen können. Durch das kontrollierte Einführen von Variabilität stellen wir sicher, dass zukünftige Verbesserungen keine breaking changes für gut implementierte Clients darstellen.
Die zufälligen Felder dienen als sanfte, aber beständige Erinnerung daran, dass JSON-APIs darauf ausgelegt sind, erweiterbar zu sein. Clients, die diese Felder korrekt behandeln, passen sich nahtlos an zukünftige API-Verbesserungen an, während diejenigen, die dies nicht tun, sofort während der Entwicklung Feedback erhalten.
Wir glauben, dass dieser proaktive Ansatz, inspiriert von erfolgreichen Implementierungen im breiteren Tech-Ökosystem, zu einer robusteren und zukunftssicheren API-Plattform für all unsere Nutzer führen wird.
