Versionierung

Kompatibilitätsversprechen innerhalb von v1

Unter /api/v1 streben wir nur nicht-breaking Änderungen an. Sichere Änderungen sind unter anderem:

• Neue Endpunkte hinzufügen
• Optionale Request-Felder hinzufügen
• Response-Felder hinzufügen
• Neue Event-Typen oder Scopes hinzufügen (opt-in)
• Dokumentation präzisieren

Behandeln Sie unbekannte Response-Felder als ignorierbar, damit Clients vorwärtskompatibel bleiben.

Breaking Changes

Breaking Changes erfordern eine neue Major-URL-Version (zum Beispiel /api/v2), etwa:

• Felder entfernen oder umbenennen
• Feldtypen oder Semantik ändern
• Bisher optionale Request-Felder verpflichtend machen
• Authentifizierung oder Fehlerverträge inkompatibel ändern

Deprecation

Wenn ein Feld oder Endpunkt innerhalb von v1 zurückgezogen werden muss:

1. Es wird in Docs und OpenAPI als deprecated markiert.
2. Es bleibt mindestens 90 Tage nach der Deprecation-Mitteilung verfügbar.
3. Die Entfernung erfolgt nur in einer späteren Major-Version — oder nach dem Ankündigungsfenster, falls der Pfad nicht sicher erhalten werden kann.

Verfolgen Sie Hinweise in dieser Dokumentation und in /api/v1/openapi.json (x-cowtic-compatibility).

SDK-Kompatibilität

@cowtic/sdk 1.x ist für /api/v1 vorgesehen. Additive v1-Unterstützung erscheint als Minor-Version, Korrekturen als Patch-Version und eine zukünftige /api/v2 erfordert SDK 2.x.

Empfehlungen

• Binden Sie Integrationen explizit an /api/v1.
• Nutzen Sie das OpenAPI-Dokument für Codegenerierung und Contract-Tests.
• Entwerfen Sie Clients so, dass additive JSON-Felder toleriert werden.
• Abonnieren Sie die benötigten Webhook-Event-Typen; ignorieren Sie unbekannte Typen, wenn Sie ein gemeinsames Envelope parsen.