Ir para o conteúdo

Versionamento e descontinuação

O Tarno expõe um contrato de leitura estável. Este documento descreve a política: o que conta como mudança compatível, como uma que quebra é entregue e como um integrador fica sabendo.

O schema por campo é 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.

✅ Esta política está em vigor desde 2026-09-23. Nesse dia o prefixo v1 deixou de responder, num único deploy e sem redirecionamento. Os integradores receberam o aviso pela carta de migração, com o guia antes → depois completo.

O contrato não leva versão na URL

Não há v1 nem v2 na rota. Um endpoint é https://api.tarno.cl/trademarks, e pronto. O contrato é versionado pelo seu registro de mudanças, não pela sua URL:

  • O changelog do contrato é a versão. Cada entrada diz o que mudou, quando, e sob qual dos seus sete rótulos: [ADD] acrescenta (uma rota, um campo, um parâmetro opcional) · [BEH] muda o comportamento (mesma forma, outros valores) · [BREAK] quebra · [FIX] corrige uma falha sem mudar a forma · [INT] mudança interna, sem efeito visível salvo numa falha · [DATA] o próprio corpus mudou (uma recuperação, um preenchimento, uma série corrigida) · [WITHDRAWN] uma entrada anunciada e retirada antes de sair: o contrato não mudou.
  • O OpenAPI leva a data do contrato em info.version — é um documento datado, não um número de versão semântica que ninguém incrementava. ⚠ info.version é a data do último corte do contrato, não um contador de mudanças: não se mexe a cada entrada do changelog.
  • Para saber se precisa reler o documento, leia info.x-revision e o ETag. info.x-revision é a data da entrada mais recente do changelog com efeito visível no documento (calculada na construção; [INT], [DATA] e [WITHDRAWN] não contam) e, se faltar, o servidor não conseguiu calculá-la: não a suponha. O ETag de GET /docs/openapi.json identifica o seu conteúdo exato: envie If-None-Match e um 304 diz que nada mudou, mesmo que a data não tenha se movido.

Um prefixo de versão promete algo que não se pode cumprir com honestidade: que a versão antiga continuará servindo. Manter dois contratos vivos ao mesmo tempo dobra o trabalho de cada mudança e, com um único integrador, não protege ninguém. Fica retirado.

Evolução aditiva por padrão — e o que se pede em troca

A maioria das mudanças é compatível e entra sem aviso prévio:

  • Um endpoint novo.
  • Um parâmetro de requisição novo e opcional.
  • Um campo novo num objeto de resposta.
  • Um valor novo numa enumeração de conjunto aberto, onde o contrato já documenta que ela pode crescer.

⚠ O que torna essa adição segura é uma obrigação sua, e é a única que pedimos: você precisa ignorar os campos que não conhece. Um cliente que falhe ao encontrar uma chave inesperada, ou que valide a resposta contra um schema fechado, vai quebrar com uma mudança que para todo o resto é compatível. Se a sua linguagem permitir, desserialize com additionalProperties permitido e não assuma que o formato da resposta está fechado.

O que quebra é um [BREAK] direto

Uma mudança retroincompatível é aplicada no lugar, marcada como [BREAK] no registro e avisada. Não há janela de descontinuação, não há cabeçalho de versão e não há dois contratos convivendo. Contam como [BREAK], por exemplo:

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

As remoções são mais um [BREAK]: não têm ciclo nem calendário próprios.

Como você fica sabendo

  1. A entrada no registro, com o seu rótulo e a sua data.
  2. Uma carta de migração com o mapa completo antes → depois: rota antiga → rota nova, campo antigo → campo novo, código de erro antigo → novo. ⭐ Uma única carta, mesmo quando um deploy consolida várias mudanças: treze avisos soltos são trabalho de organizar que estaríamos repassando para você.
  3. O guia de migração publicado, com uma versão escrita para um assistente de código seguir.

⛔ O que esta política NÃO faz, e por quê

Escrito no negativo de propósito, para que não volte a ser proposto como novidade.

mecanismo estado razão
Prefixo de versão na rota (v1, v2) retirado prometia dois contratos vivos ao mesmo tempo; com um integrador é custo sem benefício
Cabeçalho de versão de contrato (p. ex. um Iris-Version datado) descartado mesma razão: é a mecânica de janela com outra roupa
Cabeçalhos Deprecation / Sunset (RFC 9745 / RFC 8594) anotado como opção futura são o padrão correto se um dia houver mais de um consumidor. Hoje não há, e uma janela que ninguém usa é cerimônia
Janela mínima de 90 dias antes de remover revogado era a política anterior. Ver abaixo
Redirecionamento 308 da rota antiga para a nova descartado mantém viva a rota antiga, que é justamente o que o corte elimina

O que esta página dizia antes, e não se apaga em silêncio. Até 2026-09-20 esta política prometia que «uma mudança retroincompatível nunca é aplicada no lugar sobre v1… ela é entregue sob um novo prefixo de versão (v2)», com uma janela de pelo menos 90 dias. Esteve em vigor e foi de fato aplicada: a consolidação v1.6 completou esse ciclo inteiro e retirou denominacion / fechaDesde / fechaHasta, com o seu guia de migração. A política mudou porque a premissa que a sustentava — vários integradores com calendários próprios — nunca se concretizou.

Onde acompanhar as mudanças

  • /docs — a referência de schema ao vivo, gerada a partir do código em execução.
  • Changelog do contrato — cada mudança do contrato com o seu rótulo e a sua data, de 2026-09-17 em diante. É a versão do contrato.

O Tarno roda numa única máquina com inicialização manual pelo operador (veja o SLA), então o operador também pode contatar você diretamente para coordenar uma migração quando necessário.