📅 API‑Versionierung & Kompatibilität

🔍 Inhalt

• Voraussetzungen
• Versionierungsprinzip in ValueStreamer
• Übersicht: Module, Versionen & Media Types
• Abwärtskompatibilität & Breaking Changes
• Tipps & Best Practices
• FAQ

📋 Voraussetzungen

• Grundkenntnisse in HTTP‑Requests (Headers Accept und Content‑Type setzen)

• Zugriff auf die aktuellen YAML‑Dateien je Modul (siehe 📚 API-Dokumentationen & YAML-Dateien zum Download)

 ℹ️ Hinweis:
Falsche oder fehlende Versionsangaben im Header führen oft zu 415 Unsupported Media Type‑Fehlern.

🗂️ Versionierungsprinzip in ValueStreamer

• Versionen sind modulbezogen – jedes API‑Modul (z. B. KPI, Taskboard) hat seine eigene Version.

• Die Version wird nicht in der URL angegeben, sondern im Media Type des HTTP‑Headers (Accept und ggf. Content‑Type).

• Minor‑Änderungen (z. B. optionale Felder) sind in der Regel abwärtskompatibel.

• Major‑Änderungen (z. B. geänderte Feldnamen, Pflichtfelder, Strukturen) können Breaking Changes verursachen.

📊 Übersicht: Module, Versionen & Media Types

✨ Tipp: Prüfen Sie den Abschnitt consumes/produces in der YAML‑Datei, um den korrekten Media Type zu bestätigen.

🔄 Abwärtskompatibilität & Breaking Changes

• Alte Versionen bleiben für einen begrenzten Zeitraum nach Veröffentlichung einer neuen Version verfügbar (Dauer: abhängig vom Modul und Release‑Plan).

• Wenn eine neue Major‑Version erscheint, wird dies in den Release Notes und im Support‑Newsletter angekündigt.

• Breaking Changes können u. a. sein:

  • Pflichtfelder hinzugefügt oder entfernt

  • Feldnamen geändert

  • Response‑Struktur angepasst

• Empfohlen: Integrationen regelmäßig mit der YAML‑Spezifikation abgleichen.

⚠️ Achtung: Bei abgekündigten Versionen kann der Zugriff ohne Vorankündigung deaktiviert werden, sobald die Übergangsfrist endet.

✨ Tipps & Best Practices

• Halten Sie Accept und Content‑Type immer konsistent mit der Modulversion.

• Nutzen Sie die YAML‑Dateien als Referenz – besonders vor Updates.

• Testen Sie neue Versionen in einer Staging‑ oder Testumgebung, bevor Sie in Produktion wechseln.

• Dokumentieren Sie alle API‑Versionen, die in Ihren Systemen verwendet werden.

• Planen Sie regelmäßige Review‑Zyklen, um Änderungen frühzeitig zu erkennen.

❓ FAQ

Wie erkenne ich die aktuell gültige Version eines Moduls?
In der YAML‑Datei des Moduls im Feld info.version sowie im Abschnitt produces/consumes.

Muss ich die Version auch im URL‑Pfad angeben?
Nein, die Version wird ausschließlich im Media Type des Headers gesetzt.

Was passiert, wenn ich den falschen Media Type nutze?
Die API antwortet mit 415 Unsupported Media Type.

Erhalte ich Vorwarnung, bevor eine alte Version abgeschaltet wird?
Ja, über Release Notes und Support‑Kommunikation. Die Vorlaufzeit variiert nach Modul.