API-Versionierung
Die XBezahldienste-Spezifikation folgt Semantic Versioning (semver) (öffnet in neuem Tab): Versionsnummern haben die Form MAJOR.MINOR.PATCH. Diese Konvention regelt unmittelbar, wie Bezahldienste ihre API-Endpunkte strukturieren müssen.
Was die Versionsnummer bedeutet
| Segment | Beispiel | Bedeutung |
|---|---|---|
| MAJOR | 1 → 2 | Inkompatible Änderung — bestehende Clients können die neue Version nicht ohne Anpassung nutzen |
| MINOR | 1.1 → 1.2 | Neue Funktionen, rückwärtskompatibel — bestehende Clients arbeiten weiterhin unverändert |
| PATCH | 1.2.0 → 1.2.1 | Fehlerbehebung, rückwärtskompatibel — keine funktionale Änderung für Clients |
URL-Versionierung: nur Major-Versionen erhalten einen neuen Pfad
Der URL-Versionspräfix (/v1/, /v2/) entspricht ausschließlich der Major-Version:
/v1/paymenttransaction/{originatorId}/{endPointId} ← alle 1.x-Versionen
/v2/paymenttransaction/{originatorId}/{endPointId} ← alle 2.x-Versionen (zukünftig)
Minor- und Patch-Versionen verändern den URL-Pfad nicht. Ein Bezahldienst, der Version 1.2.0 implementiert, bedient denselben /v1/-Endpunkt wie eine Implementierung auf Version 1.0.0 oder 1.1.0.
Manche API-Implementierungen legen für jede Minor-Version einen eigenen Pfad an (z. B. /v1.1/, /v1.2/). Das widerspricht den etablierten Regeln des semver-konformen API-Designs (öffnet in neuem Tab) und erzwingt unnötige Anpassungen bei allen angebundenen Online-Diensten, obwohl sich die Schnittstelle für diese gar nicht geändert hat.
Was Rückwärtskompatibilität bedeutet
Eine Minor- oder Patch-Version ist dann rückwärtskompatibel, wenn Online-Dienste, die die Schnittstelle auf einer älteren 1.x-Version implementiert haben, ohne Codeänderung weiterhin korrekt funktionieren. Konkret:
- Neue optionale Felder im Request — ältere Clients senden sie nicht; der Bezahldienst muss deren Fehlen tolerieren.
- Neue Felder in der Response — ältere Clients ignorieren unbekannte Felder; das ist kein Fehler.
- Keine Pflichtfelder hinzugefügt — das würde bestehende Requests ungültig machen.
- Keine Felder entfernt oder umbenannt — das würde bestehende Clients brechen.
- Keine Typänderungen — z. B.
stringzuintegerist ein Breaking Change.
Solange diese Regeln eingehalten werden, bleibt der /v1/-Pfad gültig für alle 1.x-Implementierungen.
Unterstützte Versionen im DVDV
Das DVDV-Feld ServiceElementText.Versionen enthält ein JSON-Array mit den vom Bezahldienst unterstützten Major-Versionspräfixen:
{ "Versionen": ["v1"] }
Dieses Array listet URL-Präfixe (v1, v2), keine vollständigen semver-Versionen. Ein Bezahldienst, der Version 1.2.0 implementiert, trägt dort "v1" ein — nicht "v1.2" oder "v1.2.0".
Unterstützt ein Bezahldienst während einer Übergangsphase sowohl v1 als auch v2, listet er beide:
{ "Versionen": ["v1", "v2"] }
Der X-XBezahldienste-Version-Header
Online-Dienste können in jedem Request den HTTP-Header X-XBezahldienste-Version mitsenden, der angibt, nach welcher Spezifikationsversion die Anfrage formuliert ist:
X-XBezahldienste-Version: 1.2.0
- In Version 1.x ist dieser Header optional.
- Ab Version 2.0 der Spezifikation ist er als verpflichtend vorgesehen.
Der Header dient der Diagnose und dem Monitoring — er wechselt den Endpunkt nicht. Ein Request mit X-XBezahldienste-Version: 1.2.0 an /v1/paymenttransaction/... ist korrekt und erwartet.
Zusammenfassung: Anforderungen an Bezahldienste
| Anforderung | Begründung |
|---|---|
Minor- und Patch-Updates unter /v1/ ausliefern | Rückwärtskompatible Änderungen erfordern keinen neuen Pfad |
Neuen /v2/-Endpunkt erst bei Breaking Changes einführen | Nur Major-Versionen rechtfertigen einen Pfadwechsel |
| Optionale neue Felder im Request tolerieren | Ältere Online-Dienste senden diese Felder nicht |
| Unbekannte Felder in der Response nicht ablehnen | Online-Dienste ignorieren unbekannte Felder |
Versionen-Array im DVDV mit Präfixen pflegen, nicht mit Vollversionen | DVDV enthält URL-Präfixe (v1), keine semver-Strings |