FEATURE ROLLOUT · DOCUMENTAÇÃO

Versionamento, compatibilidade e erros

Fixe contratos em automações, trate respostas por código e atualize componentes de forma previsível. Mensagens humanas ajudam a depurar, mas nunca devem ser a única condição de controle do pipeline.

Superfícies versionadas

API, catálogo, CLI, imagem Docker e documentos possuem ciclos diferentes. Fixe a superfície que participa da automação e use latest apenas quando aceitar atualizações contínuas.

API /api/v1Ingestão compatível; mudanças incompatíveis exigem uma nova versão de rota

API /api/v2Management API, catálogo, test runs, OIDC e gate contextuais

catalog.versionO valor atual é 2 e entradas antigas retornam CATALOG_VERSION_UNSUPPORTED

CLISiga a versão semântica exibida por fr --version

DockerTags v* e SHA são reproduzíveis; latest acompanha o canal principal

DocumentosCada gravação cria uma versão imutável dentro do portfólio

Política de compatibilidade

Campos opcionais podem ser adicionados sem troca da versão principal. Remoções, mudanças de significado, novos campos obrigatórios ou alteração incompatível de status exigem nova versão e guia de migração. Clientes devem ignorar campos desconhecidos e validar os campos que consomem.

Estado atual

Consulte o Changelog e GET /api/version antes de atualizar; em ambientes críticos, fixe a imagem por tag v* ou sha-* e os clientes pela URL versionada do artefato.

Leia o envelope de erro

Todas as APIs públicas descritas no OpenAPI retornam erros com error, code, details, requestId, retryable e docUrl. Use primeiro o status HTTP, depois code; trate a mensagem como explicação para humanos.

json

{
  "error": "Sync recusado: o catálogo não mapeia 100% da prontidão.",
  "code": "CATALOG_COMPLETENESS_FAILED",
  "details": { "violations": [{
    "code": "READINESS_UNMAPPED",
    "featureId": "LBP-PIX-001",
    "missingPoints": 40,
    "message": "40 ponto(s) de prontidão não estão mapeados."
  }] },
  "requestId": "req_01H…",
  "retryable": false,
  "docUrl": "https://feature-rollout.dev/docs/reference/versioning-errors#estrategia-de-cliente"
}

Implemente uma estratégia de cliente

400/422Corrija a entrada; não repita automaticamente

401Renove ou substitua a credencial

403Revise papel, escopo e trust level

404Redescubra o recurso dentro do escopo autenticado

409Leia o corpo: pode ser duplicidade idempotente ou gate bloqueado

429Aguarde Retry-After quando presente

5xxRepita com backoff apenas operações idempotentes

Correlação

O mesmo requestId aparece no corpo do erro e no header x-request-id. Preserve-o nos logs e envie-o ao suporte; respostas binárias e sucessos também expõem o header.

Use os contratos legíveis por máquina

Baixe o OpenAPI 3.1 para descobrir as APIs públicas de automação e use llms.txt para entregar o mapa documental a agentes. A referência descreve somente operações suportadas; rotas internas do dashboard continuam explicitamente separadas.