Compatibilidade¶
Esta é a página mais importante do site para quem vai mudar alguma coisa.
O cliente e a API são publicados separadamente. O cliente vive no PyPI, é instalado por terceiros e atualizado quando eles quiserem — talvez nunca. O servidor não pergunta com quem está falando. Disso decorre uma regra com três faces, e satisfazer uma não é satisfazer a regra.
1. O contrato HTTP¶
Nada pode:
- rejeitar um payload que hoje é aceito;
- alterar o formato de uma resposta de sucesso;
- introduzir um novo código de status numa rota existente;
- remover um label de métrica que algum painel consome;
- alterar o esquema de segurança publicado no OpenAPI.
2. Os clientes que já estão em produção¶
O cliente compara o status exatamente:
Isso tem uma consequência que costuma pegar as pessoas de surpresa: devolver
201 onde antes vinha 200 quebra a frota, embora 201 seja "mais correto".
Uma mudança de sucesso também é uma quebra.
O corolário prático
Não existe mudança de resposta segura só porque a semântica melhorou. A pergunta certa não é "esta resposta está mais certa?", e sim "algum cliente de qualquer versão já publicada consegue notar a diferença?".
3. Os dados que já estão gravados¶
Parâmetro já salvo tem que continuar decifrando e continuar sendo gravável.
- O envelope criptográfico é contrato congelado entre dois artefatos liberados em datas diferentes — ver Envelope criptográfico.
- Documento gravado antes de um campo novo existir não pode passar a dar
erro. No Mongo um filtro por
nullcasa com campo ausente, e é isso que torna possível migrar preguiçosamente, sem script de migração.
O que não é contrato¶
Um caminho que hoje termina em exceção não tratada ou em falha silenciosa não é contrato. Ninguém consegue depender de um processo que morre. Corrigir um crash não quebra compatibilidade, mesmo que mude o que o cliente observa.
Isto não é verificado por CI¶
Vale dizer com todas as letras: nenhum teste automatizado garante o que está nesta página.
O que existe é tests/test_openapi_contrato.py, que congela apenas o
securitySchemes e o bloco security de cada rota. Ele não congela as rotas
em si, nem os métodos, nem os status de sucesso, nem o formato das respostas. E
nenhum job cruza os dois repositórios.
A regra é sustentada por revisão, não por teste. Ela importa mais do que nunca imediatamente antes de uma liberação coordenada dos dois lados.
Ordem de liberação¶
Quando uma mudança precisa acontecer nos dois lados, a ordem é sempre a mesma:
- Servidor primeiro, inerte. Toda mudança de comportamento observável entra atrás de uma configuração cujo default reproduz o estado atual. O servidor novo se comporta exatamente como o antigo.
- Cliente depois. Publicado no PyPI, adotado no ritmo de quem consome.
- A virada por último, quando a telemetria mostrar que não há mais cliente antigo — e só então.
Dois exemplos reais desse padrão estão documentados:
READ_AUTH_MODE e
USER_EDITABLE_ENFORCEMENT.
Nos dois casos o default é o comportamento histórico, e a promoção depende de
uma medição, não de uma data.