Wie die Versionierung der Sally API funktioniert
Die Version der Sally API ist das erste Pfadsegment: /v1.0. Ein gleitendes /v1 gibt es bewusst nicht, ein notierter Pfad bedeutet also weiterhin das, was er bedeutet hat. Diese Seite erklärt, was das Einfrieren einer Version heißt und welche Änderungen eine neue Version bekommen.
Schnellnavigation
- Die aktuelle Version
- Was Einfrieren heißt
- Was keine neue Version bekommt
- Die Ausnahme: der Health Check
1. Die aktuelle Version
| Version | Status | Pfad |
|---|---|---|
1.0 | Aktuell, wird aktiv weiterentwickelt, noch nicht eingefroren | /v1.0 |
Version 1.0 kann sich noch so ändern, dass ein Client bricht. Betrachte sie vorerst als beweglich. Jede Änderung steht in den Release Notes. Wir sagen Bescheid, sobald die Version eingefroren ist.
2. Was Einfrieren heißt
Ist eine Version eingefroren, antwortet sie für immer genau so wie in diesem Moment und wird nie wieder geändert. Weitergearbeitet wird an der nächsten Version (/v1.1), und wer das alte Verhalten will, bleibt einfach auf seinem Pfad. Ein Umbau, der dafür zu groß ist, wird eine neue Hauptversion (/v2).
3. Was keine neue Version bekommt
Eine neue Version entsteht nur für eine Änderung, die einen Client brechen könnte. Eine rein ergänzende Änderung bekommt keine: Ein neuer Endpunkt, ein neues Feld oder ein neuer Enum-Wert erscheint in der Version, die du ohnehin nutzt.
Dein Client muss deshalb zweierlei vertragen: Felder, die er nicht kennt, und Enum-Werte, die er noch nie gesehen hat. Ein Parser, der eines von beidem ablehnt, bricht an einer Änderung, die harmlos gedacht war.
4. Die Ausnahme: der Health Check
GET /health trägt bewusst keine Version. Eine Verfügbarkeitsprüfung sagt nichts über den Vertrag, und ein Monitor sollte einem Versionswechsel nicht folgen müssen.