Versão da API e compatibilidade

Como a versão viaja

Você não precisa fazer nada: o SDK manda a versão nos dois canais, com a constante que sobe junto com o pacote. É por isso que declarar importa — sem o cabeçalho, "a versão atual" mudaria debaixo do seu App no dia em que a atual mudasse, que é o "todo mundo quebra ao mesmo tempo" que a negociação existe para evitar.

Um canal só: o cabeçalho x-trivo-api-version, no REST e no gateway, sem parâmetro de consulta equivalente. Um segundo canal traria junto uma regra de precedência, e não serve a ninguém — esta API exige authorization por cabeçalho de qualquer jeito, então quem não manda cabeçalho não conecta.

x-trivo-api-version: 1

• Não mandar nada é válido, e responde a versão atual (hoje 1) — é o que acontece com um cliente próprio, escrito noutra linguagem. Com o SDK a versão vai declarada, que é o certo para código que fica de pé.
• Pedir uma versão que não existe é recusa, com UNSUPPORTED_VERSION e a lista do que vale em validVersions. Servir a atual a quem pediu outra entregaria dado com a forma errada, em silêncio.
• Não existe /api/v1, e nunca vai existir: um caminho versionado é uma segunda superfície de autorização com outro nome.

O que pode mudar sem trocar de versão

Dentro de uma versão, campo opcional pode nascer a qualquer momento — e o seu cliente precisa ignorar o que não conhece. O que não acontece dentro de uma versão: campo removido, campo renomeado, campo com o tipo trocado. Qualquer um dos três exige versão nova, e a antiga continua respondendo para quem a pedir.

Não descarte o que você não conhece

O corolário do parágrafo acima é o que mais custa caro na prática. Um cliente que valide o evento ou a resposta contra um esquema fechado e jogue fora os campos desconhecidos vai apagar em silêncio tudo o que nascer depois da versão dele — e o sintoma aparece meses adiante, como "o Trivo não manda esse campo".

O que exige versão nova

• Campo removido.
• Campo renomeado.
• Campo com o tipo trocado.

Qualquer um dos três exige versão nova, e a antiga continua respondendo para quem a pedir. O mesmo vale para os códigos de erro: renomear ou remover um código existente é quebra de contrato, e o que pode acontecer é um código novo aparecer — trate o desconhecido como "falhou, e eu não sei classificar", e não como impossível. O catálogo está em Erros.

O que não é versionado

Teto não é contrato de versão. Os números de Limites e ritmo são decisão de operação: se mudarem, mudam para mais folgado, e a forma da recusa continua a mesma. Escreva o seu bot contra a forma.

A copy também não. O message de uma recusa é texto em português para gente ler, e vai mudar quando a escrita melhorar. O que é estável é o code — ramificar na frase transforma copy em contrato sem ninguém ter decidido isso.

A chave de assinatura, tampouco. Ela roda sem trocar a versão da API, e é por isso que fixá-la no código quebra o seu endpoint num dia qualquer. O chaveiro e a rotação estão em Assinatura das entregas.