Política de versões da API Unite Research
Esta política cobre a API pública de leitura em https://research.unitebr.com/api/v1 e o servidor MCP em https://research.unitebr.com/mcp. A versão da API é 1.0.0; a versão do servidor MCP é 1.1.0. Não há versão descontinuada nem data de desativação anunciada.
Versionamento e compatibilidade
O caminho /api/v1 identifica a versão principal do contrato. O cabeçalho API-Version informa a versão semântica. Os aliases /api/charts, /api/charts/{chart_id}, /api/citation e /api/health continuam apontando para v1.
Correções e novos campos opcionais podem ser publicados em v1. Remover ou renomear campos, mudar tipos ou alterar o significado de valores existentes exige uma nova versão principal em outro caminho. Clientes devem tolerar campos adicionais e preservar unidades, períodos, populações e comparações.
A atualização editorial dos dados é independente da versão do contrato. A revisão aparece em version ou dataset_version. Cursores são vinculados à revisão e à consulta; se ficarem inválidos após uma atualização, a API responde 400 e o cliente deve reiniciar a consulta sem cursor.
Descontinuação e migração
Qualquer futura descontinuação será anunciada nesta página e na documentação com antecedência mínima de 90 dias, acompanhada da rota substituta, instruções de migração e data prevista. Durante o período anunciado, as respostas da versão afetada terão cabeçalhos Deprecation e Link para a política; Sunset somente será enviado quando existir uma data efetiva de encerramento. Hoje esses cabeçalhos não são enviados porque v1 permanece ativa.
Idempotência e leitura
GET, HEAD e OPTIONS não alteram dados. As três ferramentas MCP também são somente leitura e idempotentes. Idempotency-Key não é exigido nem implementa armazenamento de resultados: não há operação de escrita, cobrança ou criação de jobs nesta API. Um GET repetido continua sendo uma consulta. Use ETag e If-None-Match para revalidação com resposta 304.
As consultas retornam imediatamente; não há fila assíncrona, webhook de conclusão ou polling de jobs. A paginação por cursor divide os resultados em respostas pequenas.
Disponibilidade e uso
O serviço é público e não exige chave ou login. O firewall aplica 300 requisições por IP a cada 60 segundos, em janela fixa e por região, em /api/* e /mcp. Excesso retorna HTTP 429 em texto simples; sem Retry-After, aguarde pelo menos 60 segundos. RateLimit-Limit e RateLimit-Policy anunciam essa política nas respostas permitidas, sem indicar saldo individual. O endpoint de saúde informa a versão da base e as contagens publicadas, sem representar SLA. Para falhas transitórias, faça tentativas limitadas com espera progressiva. Respeite HTTP 429 e Retry-After quando presente; erros 400/404 exigem correção da consulta.