Versionierung

Die API ist im URL-Pfad versioniert. Wir ändern Antwortformen innerhalb einer Version nicht stillschweigend. Breaking Changes erhalten einen neuen Pfad.

Aktuelle Version

v1. Alle Endpoints liegen unter /v1/…. Wenn du keine Version in deinen Client-URLs festlegst, bricht deine Integration, sobald wir v2 veröffentlichen.

Was als Breaking Change zählt

Ein Feld aus einer Antwort entfernen.
Ein Feld umbenennen.
Den Typ eines Feldes ändern (z. B. number → string).
Die Validierung eines bestehenden Endpoints so verschärfen, dass zuvor akzeptierte Requests abgelehnt werden.
Die URL eines Endpoints ändern.

Was nicht breaking ist

Neue optionale Antwortfelder hinzufügen.
Neue Endpoints hinzufügen.
Neue Query-Parameter hinzufügen, deren Defaults das aktuelle Verhalten beibehalten.
Neue Enum-Werte hinzufügen (z. B. ein neues Allergen). Clients sollten unbekannte Enum-Werte sauber behandeln.

Deprecation-Richtlinie

Wenn wir irgendwann v2 veröffentlichen:

v1 bleibt nach Veröffentlichung von v2 mindestens 12 Monate in Betrieb.
Die Deprecation-Zeitleiste wird vorab über den Changelog und per E-Mail an alle aktiven Konten angekündigt.
Antworten auf der deprecated Version enthalten einen Sunset-Header gemäß RFC 8594.

Beta-Features

Neue Endpoints können unter einem /v1/beta/…-Präfix veröffentlicht werden. Alles unter beta kann sich ohne Ankündigung ändern und ist bis zur Promotion von Versionsgarantien ausgeschlossen.