Versionierung

Jeder Endpunkt antwortet auf zwei Pfaden:

POST /api/v1/payments/create     versioned, use this
POST /api/payments/create        unversioned, permanently supported

Beide führen heute identischen Code aus.

Verwenden Sie den versionierten Pfad. Nur so können Sie sicher sein, dass eine zukünftige Änderung Sie nicht erreicht. Eine Integration auf dem unversionierten Pfad erhält, worauf „unversioniert“ zum jeweiligen Zeitpunkt verweist, und das ist heute v1, eines Tages aber vielleicht nicht mehr.

Der unversionierte Pfad ist ein dauerhafter Alias, keine Abkündigung. Er wird nicht entfernt. Es gibt Integrationen, die nicht aktualisiert werden können, etwa Plugins, die Händler nach ihrem eigenen Zeitplan oder nie aktualisieren, und diese müssen weiter funktionieren.

Jede Antwort gibt an, welche Version sie bedient hat:

X-API-Version: v1

GET /api/versions listet auf, was existiert und zu welcher Version Ihre Anfrage aufgelöst wurde.

Was als Breaking Change gilt

Wir kündigen Breaking Changes vorher an. Dieses Versprechen bedeutet nur dann etwas, wenn wir uns über den Begriff einig sind.

Wird ohne Ankündigung in der aktuellen Version ausgeliefert:

• ein neuer Endpunkt
• ein neues optionales Request-Feld
• ein neues Response-Feld
• ein neuer Enum-Wert, den Clients tolerieren müssen
• eine gelockerte Validierungsregel, die mehr Eingaben akzeptiert
• eine Korrektur an einer Antwort, die nie dem dokumentierten Verhalten entsprach
• jede Änderung ohne sichtbare Auswirkung auf Anfragen oder Antworten

Erfordert eine neue Version:

• Entfernen oder Umbenennen eines Request- oder Response-Felds
• Ändern des Typs oder der Bedeutung eines Felds
• Ändern des Statuscodes für ein bestehendes Ergebnis
• ein optionales Feld zum Pflichtfeld machen
• Verschärfen der Validierung, sodass bisher akzeptierte Eingaben abgelehnt werden
• Entfernen eines Endpunkts oder Ändern seines Pfads
• Ändern dessen, was passiert, wenn ein Feld weggelassen wird

Die zugrunde liegende Regel: Wenn eine Integration, die heute funktioniert, nicht mehr funktionieren oder sich anders verhalten würde, ohne dass ihr eigener Code geändert wurde, ist die Änderung ein Breaking Change.