Zum Hauptinhalt springen

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​

BereichZusage
Ressourcen-URLsBleiben über Versionen hinweg stabil, sodass Aufrufe, die auf einer Version aufbauen, in späteren Versionen weiter funktionieren.
JSON-EigenschaftsnamenBleiben stabil – vorhandene Eigenschaftsnamen werden weder umbenannt noch entfernt.
Verschachtelung und Typen von EigenschaftenStruktur und Typen vorhandener Eigenschaften bleiben stabil.
Neue EigenschaftenAntworten können ohne vorherige Ankündigung neue Eigenschaften erhalten. Ihre Integration muss Eigenschaften tolerieren, die sie nicht kennt.
Unbekannte Eigenschaften in Ihren AnfragenDie 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​

SituationWas geschieht
Ein Verhalten ist fehlerhaft oder stellt ein Sicherheitsrisiko darEs kann sich ohne vorherige Ankündigung ändern, damit die Plattform korrekt und sicher bleibt.
Eine unvermeidbare inkompatible ÄnderungSie 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.