Versionamento e descontinuação da Public API

A Public API do Chatfuel tem um único endpoint, https://panel.chatfuel.com/graphql, sem número de versão na URL nem nos cabeçalhos. Em vez de versões, ela segue uma regra: um campo publicado nunca muda de um jeito que quebre os clientes existentes. Novos recursos são adicionados ao lado dos antigos, e tudo o que precisa sair é antes marcado como obsoleto, com uma data de remoção.

O que o esquema público garante

O esquema público é o contrato entre o Chatfuel e a sua integração. Ele contém apenas os campos que o Chatfuel publicou explicitamente para uso externo; o restante da API GraphQL usada pelo painel é interno e não é algo em que você possa confiar. Depois que um campo é publicado, o Chatfuel:

• não o remove nem o renomeia sem o processo de descontinuação descrito abaixo
• não muda o tipo dele nem torna obrigatório um argumento opcional
• não remove campos de entrada que você pode enviar

Mudanças que podem acontecer a qualquer momento

Mudanças aditivas não quebram nada e podem ser lançadas sem aviso:

• novas consultas, mutações, assinaturas e campos
• novos argumentos opcionais e campos de entrada
• novos valores em enums, por exemplo, uma nova Platform ou uma nova etapa de vendas
• novos tipos em unions e novas implementações de interfaces, por exemplo, um novo tipo de mensagem em uma conversa

Escreva clientes que tolerem essas mudanças. Selecione apenas os campos de que você precisa, trate valores de enum desconhecidos com um ramo padrão e ignore membros de unions e tipos de mensagem que o seu código não conhece.

Como funciona a descontinuação

Remover um campo publicado leva três etapas:

1. O campo recebe uma marcação GraphQL @deprecated com um motivo em formato fixo: "Stop using by YYYY-MM-DD. Use X instead." (Pare de usar até AAAA-MM-DD. Use X no lugar.) Ao mesmo tempo, é lançado um substituto público, se necessário. O campo continua funcionando normalmente.
2. Depois da data informada, o campo é ocultado do esquema público. Requisições que ainda o selecionam falham com um erro de validação.
3. Mais tarde, o campo é excluído.

A data no motivo é o último dia em que você pode contar com o campo. Até lá, migrar para o substituto é seguro a qualquer momento, porque os dois funcionam em paralelo.

Como se manter atualizado

As descontinuações são listadas nas páginas de referência ao lado da operação afetada, com a data e o substituto. Ao planejar a manutenção, confira a referência das operações que a sua integração usa. Se um gerador de código no seu projeto produz tipos a partir do esquema, gere-os novamente depois de atualizar o arquivo de esquema usado no build, para que o compilador mostre qualquer campo obsoleto que você ainda use.

Mudanças no comportamento de um campo publicado que mantêm a sua forma, como uma nova regra de validação, aparecem como novos códigos de erro. Trate códigos de erro desconhecidos como uma falha genérica, como descrito em erros.

Problemas comuns

Uma consulta que funcionava ontem falha porque um campo não está definido

O campo passou da data de descontinuação e foi ocultado, ou a consulta seleciona um campo que nunca fez parte do esquema público. Compare a consulta com as páginas de referência e use o substituto documentado.

Meu código quebra com um valor que ele não conhece

Um enum ou union ganhou um novo membro, o que é uma mudança aditiva. Adicione um ramo padrão para que valores novos sejam registrados e ignorados em vez de derrubar a integração.