Política de cambios incompatibles

Descripción general

Para equilibrar el desarrollo rápido con el mantenimiento de la estabilidad, ElevenLabs cuenta con directrices específicas sobre qué se considera un cambio incompatible dentro del ámbito de la API. Aquí detallamos qué consideramos y qué no consideramos cambios incompatibles.

Cambios en respuestas y esquemas

Distinguimos cuidadosamente entre cambios aditivos y sustractivos en las respuestas de la API. Añadir nuevos campos a los modelos de respuesta no se considera incompatible. Al integrar nuestra API, es necesario que tu cliente de API ignore los campos que no reconoce y no aplique comprobaciones estrictas de tipos a las respuestas de la API. Casi todos los clientes de API modernos lo hacen de forma predeterminada.

Eliminar campos de respuesta existentes o modificar su estructura es incompatible, ya que las aplicaciones cliente pueden depender de que estos campos estén presentes y mantengan el formato esperado.

Modificaciones de parámetros

Los cambios en los parámetros de la API siguen un modelo de compatibilidad estricto. Añadir parámetros obligatorios a rutas de API existentes siempre es incompatible porque las llamadas de clientes existentes no superarán la validación. Sin embargo, añadir parámetros opcionales (aquellos con valores predeterminados o marcados explícitamente como opcionales) no es incompatible, ya que las llamadas de clientes existentes pueden continuar sin modificaciones. Del mismo modo, cualquier cambio en los tipos o formatos de los parámetros, o hacer obligatorios parámetros que antes eran opcionales, se considera incompatible, ya que altera el contrato que esperan los clientes.

Cambios en rutas de API y paths

Eliminar rutas de API o paths completos es inherentemente incompatible, ya que las aplicaciones cliente que llamen a estas rutas recibirán errores. Las rutas pueden marcarse como obsoletas; sin embargo, no se eliminarán por completo sin comunicarlo suficientemente a todos los usuarios afectados.