Política de alterações incompatíveis

Visão geral

Para equilibrar o desenvolvimento rápido e a manutenção da estabilidade, a ElevenLabs tem diretrizes específicas sobre o que é considerado uma alteração incompatível no escopo da API. Aqui descrevemos o que consideramos e o que não consideramos como alterações incompatíveis.

Alterações de respostas e esquemas

Diferenciamos cuidadosamente alterações aditivas e subtrativas nas respostas da API. Adicionar novos campos aos modelos de resposta não é considerado incompatível. Ao integrar com nossa API, é necessário que seu cliente de API ignore campos que não reconhece e não faça verificações rígidas de tipagem nas respostas da API. Quase todos os clientes de API modernos fazem isso por padrão.

Remover campos de resposta existentes ou modificar sua estrutura é incompatível, pois os aplicativos clientes podem depender da presença desses campos e da manutenção do formato esperado.

Modificações de parâmetros

As alterações nos parâmetros da API seguem um modelo rígido de compatibilidade. Adicionar parâmetros obrigatórios a endpoints existentes é sempre incompatível, pois as chamadas de clientes existentes falharão na validação. No entanto, adicionar parâmetros opcionais (aqueles com valores padrão ou explicitamente marcados como opcionais) não é incompatível, pois as chamadas de clientes existentes podem continuar sem modificações. Da mesma forma, quaisquer alterações nos tipos ou formatos de parâmetros, ou tornar obrigatórios parâmetros que antes eram opcionais, são consideradas incompatíveis, pois alteram o contrato esperado pelos clientes.

Alterações de endpoints e caminhos

Remover endpoints ou caminhos da API inteiros é inerentemente incompatível, pois os aplicativos clientes que chamam esses endpoints receberão erros. Os endpoints podem ser marcados como obsoletos, mas não serão removidos sem comunicação adequada com todos os usuários afetados.