Ir para o conteúdo

Versionamento e descontinuação

O IRIS 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://<iris-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:

  1. Anúncio. A descontinuação é anunciada no changelog, declarando a versão descontinuada, sua sucessora e a data de remoção.
  2. 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.
  3. Remoção. Após o fechamento da janela, a versão descontinuada pode ser removida. Sua remoção é registrada no changelog.

Como o IRIS 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.

Onde acompanhar mudanças

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