Kompatibilität und Deprecations

Richtlinie für Kompatibilität

Grundsätzlich erfolgen alle Änderungen an der REST API in einer Weise, die es ermöglicht bis zum Wegfall von Features (Siehe Richtlinie für Deprecations) die API ohne Update des API-Clients zu benutzen. Dadurch ist eine Kompatibilität auf Datenebene sichergestellt. Was jedoch nicht kompatibel bleibt, ist die OpenAPI-Spezifikation und damit auch die automatisch generierten API-Clients. Bestehende Anwendungen müssen ggf. angepasst werden, falls ein Update des API-Clients erfolgt.

Es kann vorkommen, das experimentelle APIs von vornherein als Deprecated markiert werden, um zu signalisieren, dass diese sich jederzeit ändern können und deren Verwendung auf eigene Gefahr erfolgt.

Richtlinie für Deprecations

Sobald ein Feature als Deprecated markiert wurde, bekommt das Feature eine Übergangszeit von mindestens Drei Monaten, damit API-Clients auf eine neuere Version migriert werden können. Die Übergangszeit kann bis auf das Ende eines vollen Quartals verlängert werden. Wenn z.B. ein Feature mit einem Verfallszeitpunkt Q1 2026 beschrieben ist, ist ab dem 1. Januar 2026 nicht mehr garantiert, dass dieses Feature weiterhin funktioniert.

Inkompatible Änderungen

Q1 2026

  • Die alte Search API unter /search wurde durch die Search-Endpunkte von Customer, Product und Receipt ersetzt.
  • Die Eigenschaft DeliveryDate in Receipt wurde durch die Eigenschaft ReceiptDate ersetzt.
  • Die Eigenschaft Segment in Customer wird erforderlich.

Q2 2026

  • Bei Filterwerten, die kein String sind gibt die API einen Fehler zurück. Wenn nach numerischen Werten gefiltert werden soll, müssen diese als String kodiert werden.