Betrieb

Versionen und Abkündigungen

Was sich innerhalb von v1 ändern darf, wie wir Änderungen ankündigen und wie lange alte Wege weiterlaufen.

Was sich in v1 ändern darf

Die Hauptversion steht im Pfad, aktuell /v1 für die REST-API und den MCP-Server. Innerhalb von v1 kommen nur Dinge dazu, nichts fällt weg:

Änderung	In v1 erlaubt	Was dein Code tun muss
Neuer Datensatz, Endpunkt oder MCP-Werkzeug	ja	nichts
Neues Feld in einer Antwort	ja	unbekannte Felder ignorieren
Neuer optionaler Parameter	ja	nichts
Neuer Fehlercode	ja	unbekannte Codes wie den HTTP-Status behandeln
Neuer Wert in einer Liste erlaubter Werte (etwa ein Bestandteil)	ja	unbekannte Werte nicht als Fehler werten
Feld umbenennen, entfernen oder seine Bedeutung ändern	nein, nur in v2	nichts, solange du v1 nutzt
Neuer Pflichtparameter	nein, nur in v2	nichts
Fehlertexte (nachricht, detail) umformulieren	ja	nicht auf den Wortlaut verlassen, nur auf code

Werte selbst ändern sich, wenn der Gesetzgeber sie ändert. Das ist keine Änderung der Schnittstelle, sondern ihr Zweck: Jede neue Stufe steht im Änderungsprotokoll.

Versionsnummern

Neben der Hauptversion im Pfad gibt es eine Produktversion nach Semantic Versioning, aktuell 1.3.0. Sie steht an drei Stellen und ist überall gleich: im Einstieg https://api.quellenkontor.dev/v1/ als produkt_version, in info.version der OpenAPI-Beschreibung und in serverInfo.version des MCP-Servers.

Die mittlere Stelle steigt bei neuen Datensätzen, Feldern, Parametern, Endpunkten und Werkzeugen.
Die letzte Stelle steigt bei Korrekturen ohne neue Möglichkeiten.
Die erste Stelle steigt nur zusammen mit einem neuen Pfad (/v2).

Abkündigung mit Deprecation und Sunset

Soll ein Endpunkt, Parameter oder Werkzeug wegfallen, passiert das nur mit einer neuen Hauptversion und in drei Schritten:

Ankündigung: Eintrag im Änderungsprotokoll und eine Mail an alle Konten, mindestens zwölf Monate vor dem Abschalten.
Kennzeichnung: Antworten des betroffenen Wegs tragen den Header Deprecation (RFC 9745) mit dem Datum der Ankündigung, Sunset (RFC 8594) mit dem Datum des Abschaltens und einen Link mit rel="deprecation" auf die Anleitung zum Umstieg.
Parallelbetrieb: Alte und neue Version laufen mindestens zwölf Monate nebeneinander. Erst nach dem Sunset-Datum antwortet der alte Weg mit 410 Gone.

So sähe eine abgekündigte Antwort aus

HTTP/2 200
Deprecation: @1790812800
Sunset: Wed, 01 Mar 2028 00:00:00 GMT
Link: <https://quellenkontor.dev/docs/versionen#abkuendigung>; rel="deprecation"

Derzeit ist nichts abgekündigt. Prüf die Header in deinem Monitoring, dann erfährst du es von selbst.

MCP-Protokollversionen

Der MCP-Server spricht die Protokollversionen 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 und antwortet in der Version, die der Client bei initialize wünscht. Neue Protokollversionen kommen dazu, ältere bleiben, solange verbreitete Clients sie nutzen. Unterschiede zwischen den Versionen stehen in der Doku zum MCP-Server, etwa Batches nur bis 2025-03-26.

SDK und CLI

Die Pakete @quellenkontor/sdk, @quellenkontor/cli und quellenkontor haben eigene Versionsnummern nach Semantic Versioning. Eine neue Hauptversion eines Pakets gibt es nur, wenn sich seine Methoden ändern. Neue Datensätze kommen in einer neuen mittleren Version dazu; ältere Pakete fragen neue Datensätze über die rohe Anfrage ab.

Fehlt etwas oder ist etwas unklar? Schreib uns, wir ergänzen die Doku.