Kompatibilität und Versionierung

Die DUST API ist im Pfad versioniert — jeder Endpunkt befindet sich unter /api/v1. Innerhalb einer Version entwickeln wir die API kontinuierlich weiter, halten uns dabei jedoch an strenge Regeln: Änderungen sind standardmäßig additiv, alles, was eine ordnungsgemäß implementierte Integration beeinträchtigen würde, durchläuft zunächst einen Abkündigungszeitraum, und die veröffentlichte OpenAPI-Spezifikation ist zu jedem Zeitpunkt die maßgebliche Beschreibung des Vertrags.

Diese Seite definiert, was „ordnungsgemäß implementiert“ für Ihre Integration bedeutet und was wir Ihnen im Gegenzug zusichern.

Was sich ohne Vorankündigung ändern kann

Diese Änderungen gelten als abwärtskompatibel. Sie können in jeder Version auftreten, und Ihre Integration muss sie tolerieren:

• Neue Endpunkte und neue Operationen für bestehende Pfade.
• Neue optionale Anfrageparameter, Header und Textkörperfelder. Bestehende Anfragen funktionieren unverändert weiter.
• Neue Felder in Antworten. Objekte werden im Laufe der Zeit erweitert.
• Neue Werte in Aufzählungsfeldern — mit der Weiterentwicklung des Produkts kommen neue Ereignistypen, Zustände und Arten hinzu.
• Neue Fehlercodes für Fehlersituationen, die zuvor mit einem generischen Code ausgegeben wurden.
• Dokumentation, der Text von Fehler-message und die Feldreihenfolge. Für Menschen lesbare Zeichenfolgen sind nicht Teil des Vertrags; die Reihenfolge von JSON-Elementen ist niemals von Bedeutung.

Eine dauerhaft kompatible Integration entwickeln

Die oben genannten Regeln sind sicher, wenn Ihr Client der üblichen Praxis eines toleranten Lesers folgt:

• Ignorieren Sie Antwortfelder, die Sie nicht erkennen. Ein Client darf bei unerwarteten Elementen niemals fehlschlagen. Verwenden Sie außerdem keine strikte Schemavalidierung, die unbekannte Felder zurückweist.
• Tolerieren Sie unbekannte Enum-Werte. Verzweigen Sie anhand der von Ihnen unterstützten Werte und behandeln Sie andere Werte ohne Fehler.
• Verzweigen Sie anhand des Fehler-code, niemals anhand von message. Codes sind stabile Kennungen; Meldungen sind lokalisiert und können umformuliert werden. Siehe Anfragekonventionen.
• Behandeln Sie IDs und Paginierungscursor als undurchsichtige Zeichenfolgen. Speichern und verwenden Sie sie erneut; analysieren oder erzeugen Sie sie niemals selbst.
• Rufen Sie nur auf, was in der veröffentlichten Spezifikation dokumentiert ist. Für Endpunkte, Felder und Verhaltensweisen, die nicht in der öffentlichen OpenAPI-Spezifikation enthalten sind, besteht keine Kompatibilitätszusage.

Eine Integration, die diese Regeln befolgt, bleibt von additiven Änderungen unberührt und wird durch die nachfolgenden Zusicherungen geschützt.

Was wir als inkompatible Änderung behandeln

Ohne den nachfolgend beschriebenen Abkündigungsprozess nehmen wir an keiner veröffentlichten /api/v1-Operation eine der folgenden Änderungen vor:

• Entfernen oder Umbenennen eines Endpunkts, Anfrageparameters oder Antwortfelds.
• Ändern des Typs oder Formats eines Felds.
• Erforderlichmachen einer optionalen Anfrageeingabe oder Einschränken der von einer Eingabe akzeptierten Werte.
• Entfernen eines Werts aus einem Aufzählungsfeld.
• Ändern des Fehler-code oder HTTP-Status, der für eine bestehende, dokumentierte Fehlersituation zurückgegeben wird.
• Verlangen einer höheren Autorisierungsstufe oder einer neuen Berechtigung für eine bestehende Operation.
• Wesentliches Ändern der Semantik einer Operation, selbst wenn ihre Struktur unverändert bleibt.

Abkündigung

Wenn wir etwas außer Betrieb nehmen oder umgestalten müssen, wird es zunächst als abgekündigt gekennzeichnet:

• Die Operation oder das Feld wird in der veröffentlichten OpenAPI-Spezifikation mit deprecated: true gekennzeichnet, und die Abkündigung wird in dieser Dokumentation vermerkt.
• Abgekündigte Funktionen bleiben ab der Ankündigung mindestens 90 Tage lang unverändert funktionsfähig.
• Sofern es einen dokumentierten Ersatz gibt, steht dieser vor oder zum Zeitpunkt der Abkündigung zur Verfügung.

Beobachten Sie die Spezifikation, nicht den Datenverkehr

Die veröffentlichte OpenAPI-Spezifikation unter /openapi.json bildet stets den aktuellen Vertrag einschließlich der Abkündigungsmarkierungen ab. Ein Vergleich der Spezifikation zwischen den Überprüfungen Ihrer Integration ist die zuverlässigste Möglichkeit, Änderungen zu erkennen.

Versionierung

Neue Hauptversionen sind bewusst selten. /api/v1 wird additiv weiterentwickelt; wir würden /api/v2 nur für eine Umgestaltung einführen, die sich nicht kompatibel umsetzen lässt. /api/v1 bliebe dann während eines langen, ausdrücklich angekündigten Migrationszeitraums unterstützt und würde niemals nach dem oben genannten Abkündigungszeitraum entfernt.

Siehe auch

• Anfragekonventionen — der gemeinsame Anfragevertrag, für den diese Zusicherungen gelten.
• Authentifizierung und API-Schlüssel — Dienstkonten und Token-Gültigkeitsdauern.
• Vollständige API-Referenz — aus der veröffentlichten Spezifikation generiert.