Versionado y obsolescencia de la Public API

La Public API de Chatfuel tiene un único endpoint, https://panel.chatfuel.com/graphql, sin número de versión en la URL ni en los encabezados. En lugar de versiones, sigue una regla: un campo publicado nunca cambia de una forma que rompa los clientes existentes. Las nuevas capacidades se agregan junto a las anteriores, y todo lo que deba desaparecer se marca primero como obsoleto con una fecha de eliminación.

Qué garantiza el esquema público

El esquema público es el contrato entre Chatfuel y tu integración. Contiene solo los campos que Chatfuel publicó explícitamente para uso externo; el resto de la API GraphQL que usa el panel es interno y no puedes depender de él. Una vez que un campo se publica, Chatfuel:

• no lo elimina ni le cambia el nombre sin el proceso de obsolescencia que se describe abajo
• no cambia su tipo ni vuelve obligatorio un argumento opcional
• no elimina campos de entrada que puedes enviar

Cambios que pueden ocurrir en cualquier momento

Los cambios aditivos no rompen nada y pueden publicarse sin aviso:

• nuevas consultas, mutaciones, suscripciones y campos
• nuevos argumentos opcionales y campos de entrada
• nuevos valores en enums, por ejemplo, un nuevo Platform o una nueva etapa de venta
• nuevos tipos en uniones y nuevas implementaciones de interfaces, por ejemplo, un nuevo tipo de mensaje en una conversación

Escribe clientes que toleren estos cambios. Selecciona solo los campos que necesitas, maneja los valores de enum desconocidos con una rama por defecto y omite los miembros de uniones y los tipos de mensaje que tu código no conoce.

Cómo funciona la obsolescencia

Eliminar un campo publicado lleva tres pasos:

1. El campo recibe una marca GraphQL @deprecated con un motivo en un formato fijo: "Stop using by YYYY-MM-DD. Use X instead." (Deja de usarlo a más tardar el AAAA-MM-DD. Usa X en su lugar.) Al mismo tiempo se publica un reemplazo público, si hace falta. El campo sigue funcionando con normalidad.
2. Después de la fecha indicada, el campo se oculta del esquema público. Las solicitudes que todavía lo seleccionan fallan con un error de validación.
3. Más adelante, el campo se elimina.

La fecha del motivo es el último día en que puedes contar con el campo. Hasta entonces, migrar al reemplazo es seguro en cualquier momento, porque ambos funcionan en paralelo.

Cómo mantenerte al día

Las obsolescencias aparecen en las páginas de referencia junto a la operación afectada, con la fecha y el reemplazo. Cuando planifiques el mantenimiento, revisa la referencia de las operaciones que usa tu integración. Si un generador de código de tu proyecto produce tipos a partir del esquema, vuelve a generarlos después de actualizar el archivo de esquema con el que compilas, para que el compilador te muestre cualquier campo obsoleto que sigas usando.

Los cambios en el comportamiento de un campo publicado que mantienen su forma, como una nueva regla de validación, aparecen como nuevos códigos de error. Trata los códigos de error desconocidos como un fallo genérico, como se describe en errores.

Problemas comunes

Una consulta que funcionaba ayer falla porque un campo no está definido

El campo superó su fecha de obsolescencia y se ocultó, o la consulta selecciona un campo que nunca formó parte del esquema público. Compara la consulta con las páginas de referencia y usa el reemplazo documentado.

Mi código falla con un valor que no conoce

Un enum o una unión recibió un nuevo miembro, lo cual es un cambio aditivo. Agrega una rama por defecto para que los valores nuevos se registren y se ignoren en lugar de hacer fallar la integración.