Versionamento e ciclo de vida da API

A API Nomos evolui o tempo todo: novas fontes, novos campos, novos filtros. Esta página explica o que isso significa para a sua integração e o que muda entre clientes padrão e clientes Enterprise.

​

Dois modelos de acesso

O versionamento controlado é um recurso dos clientes Enterprise com instância própria: a versão da API é instanciada para o cliente, ou seja, fixada na instância dedicada dele, e só muda quando a atualização é combinada. Os demais clientes consomem a API compartilhada, que está sempre na versão mais atual. Os endpoints versionados (/v1/, /v2/) são disponibilizados apenas a clientes Enterprise, após a contratação. Se você é cliente padrão, não há nada a escolher: a API que você consome é a versão atual. A versão vigente está declarada no campo version da especificação OpenAPI publicada nesta documentação.

​

Versões no caminho da URL: /v1/, /v2/

Os endpoints versionados são disponibilizados apenas a clientes Enterprise, após a contratação. Neles, a versão da API aparece como prefixo no caminho da URL: /v1/, /v2/ e assim por diante. O prefixo identifica o contrato que a sua integração consome.

• Versão maior nova (/v2/): só é criada quando há mudança que quebra compatibilidade. Mudanças compatíveis entram na versão em uso, sem mudar o prefixo.
• Convivência: durante a transição, a versão anterior (/v1/) continua disponível junto da nova, pelo prazo de descontinuação descrito abaixo, e a migração é combinada com o cliente.
• Clientes padrão: consomem a API compartilhada, sempre na versão mais atual, sem escolher versão.

Para contratar o acesso aos endpoints versionados, fale com o seu Account Executive.

​

O que é compatível e o que não é

Mudanças compatíveis entram na versão vigente, sem nova versão e sem aviso prévio. Escreva seu cliente para tolerá-las:

• novos endpoints e novas fontes de dados;
• novos campos opcionais em respostas;
• novos filtros opcionais em requisições.

Mudanças que quebram compatibilidade exigem uma nova versão, nunca uma alteração silenciosa da atual:

• remover ou renomear um campo;
• mudar o tipo ou o significado de um campo;
• alterar o contrato de uma resposta ou tornar obrigatório um parâmetro que era opcional.

​

Descontinuação

Antes de desativar uma versão, um endpoint ou um campo, a Nomos comunica com no mínimo 90 dias de antecedência. Durante a transição, a versão anterior continua disponível, e a comunicação traz o caminho de migração. Para clientes Enterprise, o aviso é enviado diretamente aos administradores técnicos da instância.

​

Acompanhar as mudanças

• A página Mudanças da API registra cada alteração relevante, com tags por tipo e feed RSS. A especificação OpenAPI reflete a versão vigente.
• A página Preview e pipeline explica como acompanhar o direcionamento de produto, que clientes Enterprise detalham com o seu Account Executive.
• Mudanças planejadas que afetem integrações são comunicadas pelos administradores técnicos cadastrados na sua organização.
• Direcionamento de produto e de integrações para clientes Enterprise é compartilhado pelo time Nomos junto à sua instância. Fale com o seu contato na Nomos ou pelo formulário de contato.

​

Próximo passo