Richtlinie für Breaking Changes

Überblick

Um schnelle Entwicklung und Stabilität in Einklang zu bringen, hat ElevenLabs klare Richtlinien dafür, was im Rahmen der API als Breaking Change gilt. Hier erläutern wir, was wir als Breaking Change betrachten und was nicht.

Änderungen an Antworten und Schemas

Wir unterscheiden klar zwischen additiven und reduktiven Änderungen an API-Antworten. Das Hinzufügen neuer Felder zu Antwortmodellen gilt nicht als Breaking Change. Bei der Integration unserer API muss Ihr API-Client unbekannte Felder ignorieren und darf keine strikten Typprüfungen für API-Antworten durchführen. Fast alle modernen API-Clients unterstützen dies standardmäßig.

Das Entfernen bestehender Antwortfelder oder das Ändern ihrer Struktur ist ein Breaking Change, da Client-Anwendungen von diesen Feldern und ihrem erwarteten Format abhängen können.

Parameteränderungen

Änderungen an API-Parametern folgen einem strikten Kompatibilitätsmodell. Das Hinzufügen erforderlicher Parameter zu bestehenden Endpunkten ist immer ein Breaking Change, da bestehende Client-Aufrufe die Validierung nicht bestehen. Das Hinzufügen optionaler Parameter hingegen – also Parameter mit Standardwerten oder ausdrücklich als optional gekennzeichnete Parameter – ist kein Breaking Change, da bestehende Client-Aufrufe unverändert weiter funktionieren. Ebenso gelten Änderungen an Parametertypen oder -formaten sowie das Pflichtmachen zuvor optionaler Parameter als Breaking Changes, da sie den erwarteten Vertrag für Clients ändern.

Änderungen an Endpunkten und Pfaden

Das Entfernen ganzer Endpunkte oder API-Pfade ist grundsätzlich ein Breaking Change, da Client-Anwendungen, die diese Endpunkte aufrufen, Fehler erhalten. Endpunkte können als veraltet markiert werden. Sie werden jedoch nicht vollständig entfernt, ohne alle betroffenen Nutzer ausreichend zu informieren.