Policy sulle modifiche incompatibili

Panoramica

Per bilanciare lo sviluppo rapido e il mantenimento della stabilità, ElevenLabs ha linee guida specifiche su ciò che viene considerato una modifica incompatibile nell’ambito dell’API. Qui illustriamo ciò che consideriamo e non consideriamo modifiche incompatibili.

Modifiche a risposte e schemi

Distinguiamo con attenzione tra modifiche additive e sottrattive alle risposte API. L’aggiunta di nuovi campi ai modelli di risposta non è considerata incompatibile. Quando integri la nostra API, il tuo client API deve ignorare i campi che non riconosce e non effettuare controlli rigorosi sui tipi delle risposte API. Quasi tutti i moderni client API lo fanno già automaticamente.

La rimozione di campi di risposta esistenti o la modifica della loro struttura è incompatibile, poiché le applicazioni client potrebbero dipendere dalla presenza di questi campi e dal mantenimento del formato previsto.

Modifiche ai parametri

Le modifiche ai parametri API seguono un rigoroso modello di compatibilità. L’aggiunta di parametri obbligatori agli endpoint esistenti è sempre incompatibile perché le chiamate client esistenti non supereranno la convalida. L’aggiunta di parametri facoltativi, invece, ovvero con valori predefiniti o contrassegnati esplicitamente come facoltativi, non è incompatibile perché le chiamate client esistenti possono continuare senza modifiche. Analogamente, qualsiasi modifica ai tipi o ai formati dei parametri, oppure rendere obbligatori parametri precedentemente facoltativi, è considerata incompatibile perché altera il contratto previsto dai client.

Modifiche agli endpoint e ai path

La rimozione di endpoint o path API completi è intrinsecamente incompatibile, poiché le applicazioni client che chiamano questi endpoint riceveranno errori. Gli endpoint possono essere contrassegnati come deprecati, ma non verranno rimossi completamente senza aver prima avvisato adeguatamente tutti gli utenti interessati.