Eine robuste API-Integration aufbauen
Gestalten Sie Ihren REST-API-Client so, dass er weiter funktioniert, während sich die API weiterentwickelt. Die Kompatibilitätsrichtlinie der REST-API beschreibt, was iGrafx stabil hält. Die folgenden Praktiken sind das, was Ihre Integration im Gegenzug tun sollte.
Voraussetzungen
- Eine funktionierende REST-API-Integration oder eine, die Sie gerade aufbauen. Siehe Auf die REST-API zugreifen.
Schritte
-
Rufen Sie Endpunkte genau wie dokumentiert auf. Die Kompatibilitätsrichtlinie gilt für die Endpunkt-URLs und die Anfrage- und Antwortformate in ihrer veröffentlichten Form. Eine Variante, die zufällig funktioniert – zum Beispiel eine Endpunkt-URL mit einem zusätzlichen Schrägstrich am Ende –, ist nicht abgedeckt und kann in einer späteren Version Fehler zurückgeben.
-
Ignorieren Sie die Reihenfolge der Eigenschaften. Lesen Sie JSON nach Eigenschaftsnamen, nicht nach Position. Behandeln Sie diese beiden Antworten als identisch:
{ "username": "joe@example.net", "lastLogin": "2024-08-26T12:31:54Z" }{ "lastLogin": "2024-08-26T12:31:54Z", "username": "joe@example.net" }Innerhalb eines Arrays spielt die Reihenfolge weiterhin eine Rolle, wenn das Array geordnet ist – behalten Sie sie dort bei.
-
Tolerieren Sie neue Eigenschaften. iGrafx kann einer Antwort ohne Ankündigung Eigenschaften hinzufügen. Ihr Client sollte weiter funktionieren, wenn er ein Feld sieht, das er nicht kennt – zum Beispiel, wenn eine spätere Version
enabledhinzufügt:{ "username": "joe@example.net", "lastLogin": "2024-08-26T12:31:54Z", "enabled": true } -
Wiederholen Sie vorübergehende Fehler. Kurze Netzwerkstörungen, DNS-Fehler und kurzzeitige Nichtverfügbarkeit kommen vor. Wiederholen Sie die Anfrage mit einer Verzögerung, die nach jedem Versuch wächst (exponentielles Backoff), und fügen Sie etwas Zufall hinzu (Jitter), damit nicht viele Clients im Gleichtakt wiederholen. Beschränken Sie Wiederholungen auf wiederholbare Anfragen wie
GETundPUT, um unbeabsichtigte Nebenwirkungen zu vermeiden. -
Validieren und bereinigen Sie Ein- und Ausgaben. Prüfen Sie Daten, bevor Sie sie senden, und prüfen und bereinigen Sie, was Sie zurückbekommen. Das schützt vor fehlerhaften Daten, unerwarteten Änderungen und Injection-Risiken.