Kompatibilitätsrichtlinie der REST-API
Diese Referenz beschreibt, was iGrafx über REST-API-Versionen hinweg stabil hält, wann sich das Verhalten ändern kann und wie Endpunkte abgekündigt werden. Welche Praktiken Ihre Integration im Gegenzug befolgen sollte, steht unter Eine robuste API-Integration aufbauen.
Kompatibilitätszusagen
| Bereich | Zusage |
|---|---|
| Ressourcen-URLs | Bleiben über Versionen hinweg stabil, sodass Aufrufe, die auf einer Version aufbauen, in späteren Versionen weiter funktionieren. |
| JSON-Eigenschaftsnamen | Bleiben stabil – vorhandene Eigenschaftsnamen werden weder umbenannt noch entfernt. |
| Verschachtelung und Typen von Eigenschaften | Struktur und Typen vorhandener Eigenschaften bleiben stabil. |
| Neue Eigenschaften | Antworten können ohne vorherige Ankündigung neue Eigenschaften erhalten. Ihre Integration muss Eigenschaften tolerieren, die sie nicht kennt. |
| Unbekannte Eigenschaften in Ihren Anfragen | Die API ignoriert JSON-Eigenschaften in Ihren Anfragen, die sie nicht kennt, und ignoriert unbekannte Abfrageparameter – so kann sich die API weiterentwickeln, ohne Ihre Aufrufe zu unterbrechen. |
Diese Zusagen gelten für die Endpunkt-URLs und die Anfrage- und Antwortformate in der veröffentlichten Form der API-Dokumentation. Eine Variante, die zufällig funktioniert – zum Beispiel eine Endpunkt-URL mit einem zusätzlichen Schrägstrich am Ende –, ist nicht durch die Richtlinie abgedeckt und kann in einer späteren Version Fehler zurückgeben. Rufen Sie jeden Endpunkt genau wie dokumentiert auf.
Wann sich das Verhalten ändern kann
| Situation | Was geschieht |
|---|---|
| Ein Verhalten ist fehlerhaft oder stellt ein Sicherheitsrisiko dar | Es kann sich ohne vorherige Ankündigung ändern, damit die Plattform korrekt und sicher bleibt. |
| Eine unvermeidbare inkompatible Änderung | Sie wird zum Zeitpunkt des Releases dokumentiert, und wo möglich geht ihr eine Abkündigungsfrist voraus. |
Wie Endpunkte abgekündigt werden
Wird ein Endpunkt ersetzt, wird das Original in der API-Dokumentation (sowohl in der eingebetteten Dokumentation als auch unter https://api.igrafx.com) als abgekündigt markiert, bevor es in einem späteren Release entfernt wird. Den aktuellen Status eines Endpunkts finden Sie in der API-Dokumentation. Bekannte Umstellungen stehen unter Abgekündigte Endpunkte.