Versionamento e depreciação da API v1

Para quem integra com a API pública do BeryX: o que é estável, o que conta como quebra e como avisamos antes de mudar. Publicada no site em /datavault/docs/versionamento-api; o resumo é a secção «Estabilidade» do portal (/datavault/developers#estabilidade, export em docs/api/public/api-stability.json, gerado por backend/scripts/api_portal.py — os prazos vêm do código). English version below.

1. O que está coberto

• O contrato é o spec público do portal (/datavault/developers/openapi.json no site; cópia versionada em public/openapi.json): as operações de /api/v1 que um token de API dvk_* consegue chamar — os GET e as escritas explicitamente abertas a tokens (gate RAG, disparo de scans, runs de orquestradores, data-diff e decisão de confiança em lote) —, com os parâmetros, os schemas de pedido e de resposta, os códigos de estado e os headers que lá estão documentados.
• O que não está no portal não tem garantias e pode mudar sem aviso: os endpoints que só a app web usa (sessão de utilizador), a administração da conta, dos tokens e da faturação, a consola BeryxTech, o chat e os streams da UI, e o /openapi.json completo que a app serve fora de produção.
• Texto não é contrato: descrições, resumos, exemplos e as mensagens legíveis dos erros (message, detail em texto) podem mudar em qualquer versão. O que é contrato é o code.

2. Versões

• A API tem semver próprio, separado da versão do produto; a regra (minor = adições compatíveis, major = quebra anunciada) e a razão de ser separada estão em PRODUTO.md §8 — esta política aplica-a, não a redefine. A versão em vigor é a entrada mais recente de changelog.json e sai em GET /api/v1/version e GET /api/v1/health (api_version) e no info.version do spec.
• Patch (X.Y.z): correções que repõem o comportamento documentado.
• Minor (X.y.0): só adições (§3).
• Major (X.0.0): quebras (§4), sempre depois de uma depreciação (§5).
• O prefixo /api/v1 não acompanha o semver: uma major pode retirar o que foi depreciado sem mudar de prefixo. Se um dia existir /api/v2, o /api/v1 continua a responder pelo menos durante a janela de depreciação.

3. Mudanças compatíveis (minor)

Uma versão minor só acrescenta:

• operações novas, parâmetros opcionais novos e headers de resposta novos;
• campos novos nas respostas — o teu cliente deve ignorar campos que não conhece (o SDK Python já o faz);
• valores novos em enums de resposta — trata um valor desconhecido como «outro» em vez de falhar;
• code novos (razões, bloqueadores, erros).

code estáveis. Os code das razões da decisão de confiança (GET /datasets/{dataset_id}/trust-decision), dos bloqueadores e avisos da readiness (GET /domains/{domain_id}/readiness) e dos erros com detail = {code, message} são estáveis: o mesmo code quer sempre dizer o mesmo; só o texto pode mudar.

Envelopes com schema_version — os factos de confiança (trust-facts.md) e os feeds de BI: campos novos só no fim; o schema_version só sobe numa quebra, e essa quebra segue esta política.

4. O que é uma quebra (major)

• remover ou renomear uma operação, um parâmetro, um campo ou um valor de enum;
• mudar o tipo ou o formato de um campo ou parâmetro (ex.: string → integer, data → data-hora);
• tornar obrigatório um parâmetro ou campo de pedido que era opcional, ou apertar a validação de modo que um pedido antes aceite passe a ser recusado (limites menores, padrões mais estritos);
• mudar o significado de um campo, de um code ou do estado HTTP de uma situação (ex.: 404 → 403);
• baixar o máximo de limit ou mudar a ordenação por omissão de uma listagem;
• passar a exigir autenticação numa operação pública, ou retirar a um token uma operação que ele podia chamar.

Uma quebra só sai de duas formas: numa versão de caminho nova (/api/v2, §2), com /api/v1 sem mudanças, ou numa versão major depois do processo de depreciação (§5).

Exceção de segurança. Se manter um comportamento expõe dados ou permite abuso, podemos mudá-lo sem janela. Fica no changelog com o tipo security e é comunicado aos admins dos workspaces com tokens de API ativos.

O que o CI verifica. api_portal.py build --check falha se o export do portal não corresponder às rotas. api_portal.py guard compara o contrato com o da base e classifica cada diferença em compatível ou quebra (backend/app/domain/api_contract/diff.py, cartão #367): remoções, tipos e formatos mudados, campos de resposta que podem vir null, pedidos que passam a obrigatórios, valores de enum removidos, validação mais estrita, valores por omissão mudados, códigos de estado removidos e autenticação nova. Falha se o contrato mudar sem uma versão nova no topo do changelog, e se uma quebra não vier numa major (ou com uma entrada security), listada em docs/api/BREAKING.md e, num PR, com o label api-breaking. Uma mudança de significado (de um campo, de um code ou de um estado HTTP) não se vê no spec e fica para a revisão.

5. Depreciação

1. Anúncio no changelog — entrada do tipo deprecated numa versão minor, com o que é depreciado, a alternativa e a data de fim.

2. Anúncio nas respostas — a operação passa a deprecated: true no spec e responde com (helper deprecate() em app/api/deps.py):

   • Deprecation: @<segundos desde a época> (RFC 9745) — desde quando está depreciada;
   • Sunset: <data HTTP> (RFC 8594) — a partir de quando deixa de responder;
   • Link: <url da nota de migração>; rel="deprecation"; type="text/html" (RFC 9745).

   Deprecation: @1790812800
   Sunset: Thu, 01 Apr 2027 00:00:00 GMT
   Link: <https://praxis.lbostuff.tech/datavault/developers#estabilidade>; rel="deprecation"; type="text/html"
   

   O CORS expõe os três headers, por isso um cliente no browser também os vê.

3. Janela mínima de 180 dias entre o anúncio e o Sunset (o deprecate() recusa uma janela menor). Durante a janela a operação continua a responder como antes.

4. Comunicação direta aos admins dos workspaces com tokens de API ativos, no anúncio e antes do fim.

5. Fim — no Sunset, a remoção sai numa major, com uma entrada removed no changelog.

6. SDK

O SDK Python (beryx-sdk, sdk/README.md) tem versões e tags próprias (sdk-v*). Suportamos as duas minor mais recentes (N e N-1): recebem correções e acompanham a API. Versões mais antigas continuam a funcionar enquanto a API não tiver quebras — os tipos do SDK toleram campos novos —, mas sem correções. Uma depreciação na API que afete o SDK sai numa minor do SDK dentro da janela de 180 dias.

7. Rate limits e quotas

• Cada token tem um limite de pedidos próprio, além do limite por IP. Os valores em vigor vêm nas respostas (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; os endpoints de saúde estão isentos); acima do limite a API responde 429 com Retry-After (segundos). Os valores são configuração do serviço (app/api/ratelimit.py), não contrato fixo.
• As quotas do plano (fontes, datasets, scans e relatórios por mês) estão na página de preços e no catálogo de planos (app/domain/billing/plans.py); acima de uma quota a API responde 402 com {detail, plan, limit}.
• Os limites e as quotas podem mudar: um aumento aplica-se logo; uma redução é anunciada com pelo menos 30 dias de antecedência (changelog e comunicação aos admins), exceto medidas contra abuso, que podem ser imediatas.

8. Reportar um problema

• Uma resposta que contradiga o contrato é um bug nosso. Escreve para suporte@praxis.lbostuff.tech (assunto «API») com o método e o caminho, o estado HTTP, a hora (UTC), o X-Request-ID da resposta (nos erros vem também em request_id) e a resposta de GET /api/v1/version (version, build_sha, api_version). Nunca envies o token; se o expuseste, revoga-o em Definições → Tokens de API.
• Corrigimos o comportamento para cumprir o contrato (patch, tipo fixed); se o erro estava no contrato, a correção segue esta política.
• Vulnerabilidades: o contacto em /.well-known/security.txt (SEGURANCA.md).

Para quem mantém a API

1. Mudaste algo no spec público? python scripts/api_portal.py diff (compara com o export versionado e classifica cada diferença em breaking ou compatible) → entrada nova no topo de changelog.json → API_VERSION em backend/app/version.py → make openapi na raiz (o mesmo que python scripts/api_portal.py build, regenera docs/api/public/) → commit. No CI correm build --check e guard. Uma quebra pede ainda a versão major, a secção dessa versão em docs/api/BREAKING.md com cada rota partida entre crases e o label api-breaking no PR.
2. Depreciar: deprecated=True na rota, deprecate(response, sunset, link, since=…) no endpoint e a entrada deprecated no changelog.
3. O praxis-site copia docs/api/public/ para content/developers/ e este documento para content/docs/api/ (pnpm sync:docs). O pnpm build do site corre scripts/check_developers.mjs: valida a cópia (versão do spec = topo do changelog, secções pt/en, política publicada com os mesmos prazos) e, com PRAXIS_PRODUTO_DIR, recusa-a se não for igual, byte a byte, a docs/api/public/.
4. Uma operação pública nova responde com um modelo *Out (response_model=), nunca com um -> dict sem schema: o guard não vê dentro de uma resposta sem schema, por isso não dá por um campo removido. backend/tests/test_api_untyped_ratchet.py chumba a operação nova. As que ainda não têm schema estão em backend/tests/api_untyped_allowlist.json, e essa lista só encolhe. O modelo declara todas as chaves que o dict devolve, porque o response_model corta as que não conhece.