Avaliar pela perspetiva do cliente
A tabela orienta a revisão, sem garantia universal. Novos campos podem afetar leitores estritos; novos valores enumerados podem quebrar tratamentos exaustivos. Inventarie clientes, bibliotecas e pressupostos.
| Alteração | Risco a verificar | Prova necessária |
|---|---|---|
| Remover ou renomear campo | Leitura deixa de funcionar | Migração explícita e testes de clientes. |
| Adicionar campo opcional | Leitor estrito ou conflito de nome | Testes de consumidores existentes. |
| Novo valor na resposta | Tratamento exaustivo incompleto | Comportamento para valores desconhecidos. |
| Mudar predefinição | Resultado funcional diferente | Comparar casos sem valor explícito. |
Organizar a coexistência
- Descreva estruturas antigas e novas, predefinições, erros, paginação e permissões. Execute testes de contrato com casos representativos.
- Escolha uma seleção explícita de versão. Distinga versão do serviço e do documento OpenAPI; verifique caches e gateways.
- Publique calendário, orientação e contacto. Acompanhe uso real com telemetria proporcional e prepare reversão compatível com os dados.
Separar descontinuação e encerramento
Deprecation sinaliza um recurso descontinuado; Sunset pode anunciar quando deverá ficar indisponível. Os cabeçalhos não migram clientes. Antes de retirar uma versão, reveja consumidores restantes, obrigações e recuperação.
Fontes primárias
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Versão por impacto no consumidor
Adicionar um número a uma URL não preserva automaticamente os clientes existentes. Uma alteração no tipo, valor esperado, comportamento ou resposta de erro pode ser incompatível mesmo que o caminho permaneça o mesmo.
- Inventariar clientes ativos e uso observado.
- Testar versões antigas do cliente em relação ao novo contrato.
- Publicar um período de coexistência e inspecionar o uso antes da desativação.
Fonte primária: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar o guia prático.
Tarefas API assíncronas
Um pedido aceite não demonstra que o trabalho terminou.
- Conta, operação e identificador reutilizável
- Estado, hora, intervalo e expiração
- Resultado, erro, cancelamento e efeitos restantes
- Uma tarefa autorizada e resultado verificado após interrupção
Caso de aceitação reproduzível
Exemplo fictício: estes dados não descrevem clientes nem resultados observados.
Ver dados do caso
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}Decisão esperada
Um 200 na consulta do estado não significa processamento concluído. Após pedir cancelamento, concluir apenas pelo resultado confirmado.
Cancelamento solicitado tarde demais
Cenário fictício: mesma tarefa J-42, segundos desde o envio. Os estados pertencem ao contrato do exemplo; HTTP não os impõe.
| Instante | Resposta e estado | Conclusão sustentada |
|---|---|---|
| +0 s | HTTP 202 · pending | Aceita para processamento; sem resultado final confirmado. |
| +5 s | HTTP 200 · running | A consulta do estado funcionou; a tarefa continua. |
| +6 s | HTTP 200 · cancel_requested | Pedido de parada registrado; cancelamento ainda não confirmado. |
| +7 s | HTTP 200 · succeeded | O processamento venceu a corrida. Mostrar o sucesso observado e verificar efeitos; não anunciar cancelamento. |
202 prova que o trabalho terminará?
Não. Confirma aceitação para processamento, não o resultado final. Consulte o estado da operação.
Fonte primária: MDN — 202 Accepted. Método relacionado: consultar o guia prático.
Atualizações de software: verificar uma mudança de signatário
Decidir se um artefacto assinado continua a corresponder ao produtor, processo e versão aprovados.
- Antes de examinar o pacote, registe produtor, chave ou identidade do certificado, emissor e processo de construção autorizados. Ligue expectativas ao software e a um canal já fiável. O artefacto não deve definir sozinho a sua política de aceitação.
- Compare a impressão do ficheiro recebido com o objeto da atestação. Verifique assinatura com as raízes de confiança previstas, depois identidade, construtor e parâmetros. Uma assinatura válida de outra identidade não satisfaz a política do serviço.
- Teste rotação anunciada, emissor inesperado, assinatura ausente e ficheiro diferente. Mantenha o artefacto pendente se a identidade nova não foi confirmada. Registe aprovação e regresso; assinatura não prova ausência de vulnerabilidades.
Caso de aceitação reproduzível
Exemplo fictício: estes dados não descrevem clientes nem resultados observados.
Ver dados do caso
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Decisão esperada
Exemplo fictício: impressão e assinatura são válidas, mas o signatário difere do aprovado. A instalação fica pendente de confirmação independente da mudança.
Fonte primária: SLSA v1.2 — Verifying artifacts. Método relacionado: consultar o guia prático.
API: descontinuação e retirada
As notas detalhadas desta edição estão disponíveis em inglês.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23