Beleid voor niet-compatibele wijzigingen

Overzicht

Om snelle ontwikkeling en stabiliteit in balans te brengen, heeft ElevenLabs specifieke richtlijnen voor wat binnen de API als niet-compatibele wijzigingen wordt beschouwd. Hier lees je welke wijzigingen we wel en niet als niet-compatibel beschouwen.

Wijzigingen in responses en schema’s

We maken zorgvuldig onderscheid tussen toevoegende en verwijderende wijzigingen in API-responses. Het toevoegen van nieuwe velden aan responsmodellen wordt niet als niet-compatibel beschouwd. Bij integratie met onze API moet je API-client velden die deze niet herkent negeren en geen strikte typecontroles voor API-responses uitvoeren. Vrijwel alle moderne API-clients doen dit standaard.

Het verwijderen van bestaande responsvelden of het wijzigen van hun structuur is niet-compatibel, omdat clientapplicaties mogelijk afhankelijk zijn van de aanwezigheid van deze velden en van het behoud van hun verwachte indeling.

Parameterwijzigingen

Wijzigingen in API-parameters volgen een strikt compatibiliteitsmodel. Het toevoegen van verplichte parameters aan bestaande endpoints is altijd niet-compatibel, omdat bestaande clientaanroepen de validatie dan niet doorstaan. Het toevoegen van optionele parameters (met standaardwaarden of expliciet gemarkeerd als optioneel) is echter niet-compatibel, omdat bestaande clientaanroepen zonder wijzigingen kunnen doorgaan. Ook wijzigingen in parametertypen of -indelingen, of het verplicht maken van eerder optionele parameters, worden als niet-compatibel beschouwd omdat ze het contract wijzigen dat clients verwachten.

Wijzigingen in endpoints en paden

Het verwijderen van volledige endpoints of API-paden is inherent niet-compatibel, omdat clientapplicaties die deze endpoints aanroepen fouten ontvangen. Endpoints kunnen als verouderd worden gemarkeerd, maar ze worden niet zonder voldoende communicatie met alle betrokken gebruikers volledig verwijderd.