GuaritaGuarita
Começar grátis
▸ API · Fundamentos

Versionamento

O que muda sem aviso, o que nunca muda dentro da v1 e como escrever um cliente tolerante.

atualizado em 2 set 2026versão v1

O que é contrato na v1

Tudo sob /v1/public é estável. Isto não muda enquanto a v1 existir:

  • Caminhos, métodos e o escopo exigido por cada endpoint.
  • Nomes e tipos dos campos que já existem — em requisição e em resposta.
  • Os códigos de erro que já existem, e o status HTTP de cada um.
  • O envelope do webhook (id, event, createdAt, data) e o formato da assinatura (t=…,v1=…, HMAC SHA-256 de t.corpo).

O que entra sem aviso

Mudanças compatíveis entram a qualquer momento, registradas no changelog. O seu cliente precisa tolerar cada uma:

Pode acontecerComo o cliente tolera
Campo novo numa respostaIgnore o que não conhece. Nunca valide “só estes campos”.
Evento novo de webhookVocê só recebe os eventos que assinou no cadastro do destino.
Código de erro novoRamifique pelo error conhecido e caia no status HTTP como fallback.
Valor novo num enum (status, risk_label, fix.kind, blockedReason)Trate valor desconhecido como neutro — nunca como “seguro”.
Endpoint novo, parâmetro opcional novoNada a fazer: o que você já chama continua igual.

O que nunca muda na v1

Conta como incompatível, e por isso não acontece dentro da v1:

  • Remover ou renomear um campo, endpoint ou código de erro.
  • Mudar o tipo de um campo, ou o significado dele.
  • Passar a exigir um parâmetro que era opcional.
  • Mudar o formato da assinatura ou o envelope do webhook.

Mudança incompatível só nasce em versão nova (/v2), anunciada nesta doc (changelog) e por e-mail ao dono da conta com pelo menos 90 dias de antecedência, com a v1 no ar por pelo menos 6 meses depois do aviso.

O formato do relatório

O relatório de GET /scans/{id}/report tem versão própria, no campo schemaVersion (hoje "1.0"). Ele é o documento do scanner e muda separado da API. Leia o campo antes de interpretar o resto — uma versão nova do relatório não muda a URL do endpoint.

Como escrever o cliente

  • Ignore campos que não conhece.
  • Ramifique por error e pelo status HTTP — nunca pelo texto da message.
  • Tolere fix ausente quando fixWithheld: true.
  • No header de assinatura, leia t e v1 por chave, não por posição.
  • Deduplique webhooks pelo id do evento.

OpenAPI e versão

O OpenAPI carrega info.version derivada da data em info.x-updated-at. Se você gera um cliente a partir dele, regenere quando essa data mudar — o changelog diz o que entrou.

Achou algo errado ou faltando? help@guarita.dev — com o x-request-id, se for sobre uma resposta.