Distinguir descrição e execução
Fixe uma versão suportada pelas ferramentas. Descreva parâmetros, corpos, respostas e requisitos de segurança. Aplicação e gateway continuam responsáveis por impor esses requisitos.
| Elemento | O que descreve | Verificação adicional |
|---|---|---|
| Esquema | Estrutura e restrições | Validação efetiva e regras de negócio. |
| Resposta documentada | Estado e conteúdo esperados | Conformidade das respostas reais. |
| Requisito de segurança | Mecanismo e direitos declarados | Controlo efetivo por operação. |
| Exemplo | Um caso ilustrativo | Coerência, ausência de segredos e casos limite. |
Rever antes de partilhar
- Verifique campos obrigatórios, tipos, intervalos, paginação, erros e formatos. Use exemplos fictícios coerentes com esquemas, sem segredos nem dados de clientes.
- Compare descrição e trocas reais em ambiente controlado. Teste falta de credenciais, permissões insuficientes e separação entre contas.
- Reveja referências externas e ferramentas que as resolvem. Expurgue a descrição pública e proteja ambientes e operações privados.
Manter a documentação
Reveja diferenças e atribua responsabilidade. Um cliente gerado ou exemplo pode respeitar a estrutura e ignorar regras de negócio. Consolas interativas precisam de ambiente adequado, permissões limitadas e indicação clara das operações modificadoras.
Fontes primárias
Compare a OpenAPI com o serviço em execução.
Uma descrição útil da OpenAPI inclui respostas a falhas, esquemas e exemplos que os clientes realmente encontram. Quando o documento e a API divergem, uma integração pode ser bem-sucedida em uma demonstração e falhar em produção.
- Compare os casos de sucesso e erro com a descrição.
- Documente os valores opcionais, a paginação e os limites de operação.
- Teste um cliente representativo antes de alterar o contrato.
Fonte primária: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar o guia prático.
Arquivos ZIP e TAR: extrair com limites de caminho e recursos
Validar caminhos, ligações e dados expandidos antes de promover os ficheiros extraídos.
- Extraia para uma pasta nova não pública com permissões mínimas. Rejeite caminhos absolutos, subida de diretórios, ligações e ficheiros especiais desnecessários. Verifique destinos resolvidos e colisões segundo o sistema, incluindo maiúsculas. Um prefixo textual não prova confinamento.
- Defina limites por ficheiro e totais de bytes escritos, entradas, profundidade, tempo e recursos. Não dependa apenas do tamanho comprimido ou declarado. Rejeite arquivos aninhados desnecessários; se permitidos, partilhe um orçamento global. Atualize biblioteca e filtros.
- Teste ../, caminho absoluto, ligação, duplicado e excesso de orçamento. Uma falha deixa o lote sem publicação e não substitui ficheiros existentes. Valide tipos e conteúdo antes da promoção; limpe a pasta verificando o destino.
Caso de aceitação reproduzível
Exemplo fictício: estes dados não descrevem clientes nem resultados observados.
Ver dados do caso
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Decisão esperada
Exemplo fictício: 2 MB comprimidos produzem 600 MB com orçamento de 100 MB. Pare ao ultrapassar bytes escritos e mantenha o lote sem publicação, mesmo com primeiros ficheiros aparentemente válidos.
Python — tarfile extraction filters and further verification
Um arquivo pequeno ou filtro garante segurança?
Não. Pode expandir muito. Acrescente limites de recursos, regras de caminhos e validação dos ficheiros extraídos.
Fonte primária: Python — tarfile extraction filters and further verification. Método relacionado: consultar o guia prático.
Erros API: tipos, estados e provas
As notas detalhadas desta edição estão disponíveis em inglês.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5