Versionamento e descontinuação

O Tarno expõe um contrato de leitura estável. Este documento declara o que é versionado, como uma mudança incompatível é entregue e por quanto tempo uma versão descontinuada continua servindo antes da remoção.

O schema por campo de qualquer versão é a referência OpenAPI (Scalar) ao vivo e interativa em /docs — ela é gerada a partir do código em execução e está sempre atualizada. Esta página descreve a política; /docs é o schema autoritativo. Os dois não são duplicados.

O contrato do prefixo `/v1`

Todo endpoint do contrato de leitura vive sob um prefixo de versão na URL, por exemplo https://<tarno-host>/v1/brands. O prefixo é a versão do contrato: /v1 denota a primeira versão major estável do contrato REST, e o servidor MCP expõe o catálogo de ferramentas correspondente para a mesma versão.

Dentro de uma versão publicada (/v1) fazemos somente mudanças retrocompatíveis:

Adicionar um novo endpoint.
Adicionar um novo parâmetro de requisição opcional.
Adicionar um novo campo a um objeto de resposta.
Adicionar um novo valor a uma enumeração aberta onde o contrato já documenta que o conjunto pode crescer.

Portanto, integradores devem tolerar campos de resposta desconhecidos e não assumir que o formato da resposta é fechado — um leitor tolerante continua funcionando ao longo de adições compatíveis.

Mudanças incompatíveis são entregues sob uma nova versão

Uma mudança retro-incompatível nunca é aplicada no lugar em /v1. Em vez disso, ela é entregue sob um novo prefixo de versão (/v2, e assim por diante), e /v1 continua servindo inalterado. Mudanças incompatíveis incluem, por exemplo:

Remover ou renomear um endpoint, campo ou parâmetro.
Mudar o tipo, as unidades ou o significado de um campo existente.
Tornar obrigatório um parâmetro anteriormente opcional.
Mudar o comportamento padrão de um modo que um cliente existente observaria.

Isso permite que um integrador migre de /v1 para /v2 no seu próprio cronograma, em vez de ser quebrado por um deploy.

Janela de descontinuação

Quando uma versão é substituída, ela é descontinuada, não removida imediatamente:

Anúncio. A descontinuação é anunciada no changelog, declarando a versão descontinuada, sua sucessora e a data de remoção.
Janela. A versão descontinuada continua servindo por uma janela declarada — pelo menos 90 dias a partir do anúncio — para que os integradores tenham tempo de migrar. A janela pode ser estendida; ela não é encurtada abaixo do que foi anunciado.
Remoção. Após o fechamento da janela, a versão descontinuada pode ser removida. Sua remoção é registrada no changelog.

Como o Tarno roda em uma única máquina com onboarding manual do operador (veja o SLA), o operador também pode contatar os integradores diretamente para coordenar uma migração quando necessário.

Descontinuação in-place com sinal antecipado (dentro de `/v1`)

Além do caminho /v1 → /v2 para quebras grandes, uma consolidação limitada de parâmetros dentro de /v1 segue este ciclo de três passos, para dar aviso antecipado sem quebrar ninguém no deploy:

Sinal antecipado. O parâmetro descontinuado continua funcionando, mas o guia old → new é anunciado e os integradores são avisados desde já.
Janela. O comportamento permissivo é mantido durante a janela declarada (pelo menos 90 dias), com o guia old → new publicado, para dar tempo de migrar.
Remoção. Ao fechar a janela, o parâmetro descontinuado é removido: um alias removido é descartado silenciosamente (200) e um valor fora do vocabulário passa a 400 validation_error.

A primeira aplicação deste ciclo foi a consolidação v1.6, já concluída: a janela fechou e os parâmetros denominacion / fechaDesde / fechaHasta foram removidos de /v1/brands, com estado como enum validado. Veja o guia de migração v1.6.

Onde acompanhar mudanças

/docs — a referência de schema ao vivo, por versão.
Changelog — cada versão, com seu anúncio de descontinuação e remoção.