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
v1deixou de responder, num único deploy e sem redirecionamento. Os integradores receberam o aviso pela carta de migração, com o guiaantes → depoiscompleto.
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-revisione oETag.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. OETagdeGET /docs/openapi.jsonidentifica o seu conteúdo exato: envieIf-None-Matche um304diz 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
- A entrada no registro, com o seu rótulo e a sua data.
- 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ê. - 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 retiroudenominacion/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.