Distinguere descrizione e applicazione
Fissare una versione supportata dagli strumenti. Descrivere parametri, corpi, risposte e requisiti di sicurezza. Applicazione e gateway devono comunque far rispettare i requisiti dichiarati.
| Elemento | Cosa descrive | Controllo aggiuntivo |
|---|---|---|
| Schema | Struttura e vincoli | Validazione effettiva e regole funzionali. |
| Risposta documentata | Stato e contenuto attesi | Conformità delle risposte reali. |
| Requisito di sicurezza | Meccanismo e diritti dichiarati | Controllo effettivo per operazione. |
| Esempio | Un caso illustrativo | Coerenza, assenza di segreti e casi limite. |
Rivedere prima di condividere
- Controllare campi obbligatori, tipi, intervalli, paginazione, errori e formati. Usare esempi fittizi coerenti con gli schemi, senza segreti o dati cliente.
- Confrontare descrizione e scambi reali in ambiente controllato. Provare credenziali mancanti, permessi insufficienti e separazione tra account.
- Verificare riferimenti esterni e strumenti che li risolvono. Ripulire la descrizione pubblica e proteggere ambienti e operazioni privati.
Mantenere la documentazione
Rivedere le differenze e assegnare un responsabile. Un client generato o un esempio può rispettare la struttura e ignorare regole funzionali. Le console interattive richiedono ambiente adatto, diritti limitati e chiara segnalazione delle operazioni modificative.
Fonti primarie
Confrontare OpenAPI con il servizio in esecuzione.
Una descrizione OpenAPI utile include risposte in caso di errore, schemi ed esempi effettivamente riscontrati dai clienti. Quando la documentazione e l'API divergono, un'integrazione può superare una demo ma fallire in produzione.
- Confrontare i casi di successo e di errore con la descrizione.
- Documentare i valori opzionali, la paginazione e i limiti operativi.
- Testare un cliente rappresentativo prima di modificare il contratto.
Fonte primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Metodo correlato: consultare la guida pratica.
Archivi ZIP e TAR: estrarre entro limiti di percorso e risorse
Validare percorsi, collegamenti e dati espansi prima di promuovere i file estratti.
- Estrai in una nuova cartella non pubblica con permessi minimi. Rifiuta percorsi assoluti, risalite, link e file speciali inutili. Controlla destinazioni risolte e collisioni secondo il sistema, comprese maiuscole e minuscole. Un prefisso testuale non prova confinamento.
- Imposta limiti per file e totali su byte scritti, voci, profondità, tempo e risorse. Non affidarti solo alla dimensione compressa o dichiarata. Rifiuta archivi annidati inutili; altrimenti condividi un budget globale. Aggiorna libreria e filtri.
- Prova ../, percorso assoluto, link, duplicato e budget superato. Un arresto lascia il lotto non pubblicabile e non sostituisce file esistenti. Valida tipi e contenuti prima della promozione; pulisci la cartella verificando la destinazione.
Caso di accettazione riproducibile
Esempio fittizio: questi dati non descrivono clienti o risultati osservati.
Vedi dati del caso
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Decisione attesa
Esempio fittizio: 2 MB compressi producono 600 MB con budget di 100 MB. Arresta al superamento dei byte scritti e non pubblicare, anche se i primi file sembrano validi.
Python — tarfile extraction filters and further verification
Un archivio piccolo o un filtro garantisce sicurezza?
No. Può espandersi molto. Aggiungi limiti di risorse, regole dei percorsi e validazione dei file estratti.
Fonte primaria: Python — tarfile extraction filters and further verification. Metodo correlato: consultare la guida pratica.
Errori API: tipi, stati e prove
Le note dettagliate di questa edizione sono disponibili in inglese.
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