API-Versionen
Versionierung der REST-API
Die REST-API von konfipay wird über Versionsnummern stabilisiert, um die langfristige Kompatibilität von Integrationen sicherzustellen. Änderungen an einer API können bestehende Implementierungen beeinträchtigen, wenn sogenannte Breaking Changes auftreten. Um solche Fälle sauber handhabbar zu machen, erfolgt die Versionierung ausschließlich über ganze Hauptversionen.
Die Version ist Teil der URL und wird in der Form
api/{version}/endpoint
angegeben, beispielsweise:
api/v2/bank-accounts
Damit obliegt es dem Aufrufer der API, zu entscheiden, welche Version genutzt wird und wann ein Wechsel auf eine neuere Version erfolgt. Ältere Versionen bleiben für einen definierten Zeitraum bestehen, sodass eine Migration planbar durchgeführt werden kann. Abkündigungen von Versionen erfolgen frühzeitig, in der Regel mehr als ein Jahr vor endgültiger Abschaltung.
Kriterien für eine neue Version
Eine neue Hauptversion (z. B. v1 → v2) wird ausschließlich veröffentlicht, wenn Breaking Changes auftreten. Als Breaking Changes gelten insbesondere:
Entfernen oder Umbenennen von Feldern in Nachrichten (JSON/XML)
Änderungen an Enumerationen oder anderen festen Wertebereichen
Änderung oder Entfernung von URLs
Entfernen oder Umbenennen von URL-Parametern
Änderung des Datentyps eines Feldes (z. B.
int→string)Einführung neuer Pflichtfelder oder Änderung von Standardwerten
Änderungen an der fachlichen Semantik oder Logik bestehender Felder (z. B. wenn ein Feld
amountbisher den Bruttobetrag enthielt und künftig den Nettobetrag ausweist)Anpassungen bei HTTP-Statuscodes (z. B. bisher 200, künftig 204)
Änderungen ohne neue Version
Folgende Anpassungen gelten nicht als Breaking Changes und können innerhalb einer bestehenden Version eingeführt werden:
Hinzufügen neuer URLs (z. B. zusätzliche Endpunkte)
Hinzufügen neuer optionaler URL-Parameter
Erweiterung von Requests um optionale Felder
Erweiterung von Responses (z. B. zusätzliche Felder, die Clients ignorieren dürfen)
Hinweis zur Client-Implementierung
Bei der Implementierung von Clients sollte berücksichtigt werden, dass Änderungen ohne neue Versionsnummer keine Inkompatibilität verursachen dürfen. Insbesondere die Erweiterung von Responses ist unproblematisch, solange Clients tolerant gegenüber unbekannten Feldern sind und diese ignorieren, anstatt sie als Fehler zu interpretieren.