Versionierung

Wie es funktioniert

Der Pfad trägt die Hauptversion, wie in /v1/api/properties. Eine zweite Hauptversion hieße vollständige Neugestaltung, liefe neben v1 statt sie zu ersetzen, und ist nichts, was wir leichtfertig vorhaben.

Die alltägliche Weiterentwicklung läuft stattdessen über eine datierte Revision. Legen Sie sie mit einem Header fest, und Ihre Anbindung behält das Verhalten, für das sie geschrieben wurde:

Skautik-Version: 2026-08-01

Ohne den Header gilt die Standardrevision Ihrer Organisation, nämlich die, die bei Erstellung Ihres ersten Schlüssels aktuell war. Sie wird nicht stillschweigend vorgerückt, eine Anbindung kann also nicht brechen, weil wir etwas ausgeliefert haben. Jede Antwort nennt die Revision, die sie bedient hat.

Was wir ohne neue Revision ändern dürfen

Diese Änderungen sind additiv, und ein Client, der eine Regel befolgt, verträgt sie alle: Ignorieren Sie Felder, die Sie nicht kennen. Ein Parser, der unbekannte Eigenschaften ablehnt, bricht bei unserer nächsten Auslieferung, und das ist vermeidbar.

• Ein neuer Endpunkt.
• Ein neuer optionaler Anfrageparameter.
• Ein neues Feld in einer bestehenden Antwort.
• Ein neuer Wert in einer Aufzählung, die Sie nur lesen.
• Ein neuer Webhook-Ereignistyp.
• Eine gelockerte Prüfregel, die zuvor etwas abgelehnt hat.

Was eine neue Revision erfordert

Alles, was einen korrekten Client brechen könnte, bekommt eine neue datierte Revision. Ihre festgelegte Revision verhält sich weiter wie dokumentiert.

• Einen Endpunkt, Parameter oder ein Antwortfeld entfernen oder umbenennen.
• Typ oder Einheit eines bestehenden Feldes ändern.
• Einen optionalen Parameter verpflichtend machen oder die Prüfung verschärfen.
• Den Vorgabewert eines Parameters ändern.
• Die Bedeutung eines bestehenden Aufzählungswerts ändern.
• Einen Webhook-Ereignistyp entfernen.

Abkündigung

Was auf dem Weg nach draußen ist, funktioniert weiter und meldet sich selbst. Abgekündigte Endpunkte liefern:

Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://skautik.com/docs/developers/api/properties>; rel="deprecation"

• Mindestens 12 Monate zwischen Abkündigung und Entfernung, für alles in einer veröffentlichten Revision.
• Wir schreiben der technischen Kontaktperson der Organisation, wenn eine Abkündigung beginnt, und erneut, wenn das Ende naht, statt darauf zu setzen, dass Sie ein Änderungsprotokoll lesen.
• Überwachen Sie den Header Deprecation in Ihrem eigenen Monitoring. Er ist die früheste mögliche Warnung und kostet nichts.

Einen haltbaren Client schreiben

• Legen Sie die Revision ausdrücklich fest, statt sich auf die Kontovorgabe zu verlassen.
• Ignorieren Sie unbekannte Felder und unbekannte Aufzählungswerte, statt daran zu scheitern.
• Behandeln Sie Kennungen als undurchsichtige Zeichenketten; lesen Sie nie ein Präfix als Bedeutung.
• Verlassen Sie sich nicht auf Feldreihenfolge, auf das Fehlen eines Feldes oder auf eine Anzahl, die die API nicht zusagt.
• Verzweigen Sie über Fehlercodes, nicht über Fehlerprosa.