Versionierung

Hauptversion im Pfad

Die Hauptversion steht im Pfad: /v1/.... Innerhalb von /v1 ändert sich die API nur ergänzend. Ein Feld oder eine Ressource fällt in /v1 nicht weg und ändert nicht seine Bedeutung.

Vertragsversion

Jede Antwort nennt in meta.schema_version die Version des Vertrags, etwa 1.0.1. Die Version folgt Semantic Versioning:

Teil	Bedeutung
Minor (`1.1.0`)	Neue Spalten oder neue Ressourcen
Patch (`1.0.1`)	Nur Änderungen an der Dokumentation

Ändert sich die Version während eines seitenweisen Abrufs, antwortet die API mit 400 invalid-cursor. Starten Sie den Abruf dann neu.

Regeln für Ihre Anbindung

Ignorieren Sie Felder, die Ihre Anbindung nicht kennt.
Lesen Sie nur die Spalten, die Sie brauchen.
Codefelder sind offene Mengen. Neue Werte können jederzeit hinzukommen. Lesen Sie die Bezeichnungen aus der Ressource /v1/codes.
Fehlercodes sind ebenfalls offen. Ein Code bekommt nie eine neue Bedeutung.

Abkündigung

Muss ein Teil der API entfallen, kündigt DIGIBIZ das mit den Headern Deprecation (RFC 9745) und Sunset (RFC 8594) an. Sunset nennt das Datum, ab dem der Teil entfällt. Version 1 nutzt diese Header noch nicht, weil nichts abgekündigt ist.

Änderungen

Version	Änderung
`1.0.1`	Nur Dokumentation. Schlüsselspalten nennen in `x-references` die Ressource, auf die sie verweisen. `gross_amount`, `payable_amount` und `plan_amount` erklären ihre Summen am selben Vorkasse-Beispiel.
`1.0.0`	Erste Version.