Distinguer description, validation et autorisation
Épinglez une version de la spécification compatible avec vos outils. Décrivez paramètres, corps, réponses et exigences de sécurité. Une déclaration de sécurité exprime une exigence : l’application et la passerelle doivent encore la faire respecter.
| Élément | Ce qu’il décrit | Vérification complémentaire |
|---|---|---|
| Schéma | Structure et contraintes des données | Validation et règles métier effectives. |
| Réponse documentée | Statut et contenu attendus | Conformité des réponses réelles. |
| Exigence de sécurité | Mécanisme et droits annoncés | Contrôle d’accès effectif par opération. |
| Exemple | Un cas illustratif | Cohérence, absence de secrets et cas limites. |
Revoir le contrat avant sa diffusion
- Vérifiez les champs obligatoires, types, plages de valeurs, pagination, erreurs et formats de contenu. Donnez des exemples fictifs cohérents avec les schémas, sans secrets ni données de clients.
- Comparez la description aux requêtes et réponses d’un environnement contrôlé. Incluez absence de justificatif, droits insuffisants et séparation entre comptes dans les tests.
- Contrôlez les références externes et les outils qui les résolvent. Maintenez une version publique expurgée et protégez les environnements et opérations privés.
Traiter la documentation comme un produit maintenu
Vérifiez les différences à chaque évolution et désignez un responsable. Un exemple ou un client généré peut être valide en forme tout en ignorant une règle métier. Une console interactive doit viser un environnement adapté, avec des droits limités et une indication claire des opérations qui modifient l’état.
Références primaires
OpenAPI : comparer le contrat au service exécuté
Une description OpenAPI utile comprend les réponses d’échec, les schémas et les exemples que rencontrent les clients. Si le document et l’API divergent, une intégration peut réussir en démonstration puis échouer en production.
- Comparer automatiquement les cas de succès et d’erreur à la description.
- Documenter valeurs optionnelles, pagination et limites de chaque opération.
- Tester un client représentatif avant une évolution du contrat.
Référence primaire : IETF RFC 9457 — Problem Details for HTTP APIs. Méthode connexe : consulter le guide pratique.
Archives ZIP et TAR : extraire sans sortir du dossier ni épuiser les ressources
Contrôler chemins, liens et volumes décompressés avant de promouvoir les fichiers d’une archive.
- Extrayez dans un nouveau dossier non public avec des droits minimaux. Refusez les chemins absolus, remontées de répertoire, liens et fichiers spéciaux inutiles au besoin. Contrôlez les destinations réellement résolues et les collisions selon le système cible, y compris la casse. Un simple préfixe textuel de chemin ne démontre pas le confinement.
- Fixez limites par fichier et cumulées sur octets écrits, nombre d’entrées, profondeur, temps et ressources du processus. N’utilisez pas uniquement la taille compressée ou déclarée. Refusez les archives imbriquées si elles ne sont pas nécessaires ; sinon appliquez un budget global à tous les niveaux. Gardez la bibliothèque et ses filtres à jour.
- Testez une entrée ../, un chemin absolu, un lien, un doublon et un dépassement de budget. Vérifiez qu’un arrêt laisse un lot non publiable et ne remplace pas des fichiers existants. Validez les types et contenus obtenus avant promotion ; nettoyez le dossier isolé selon une procédure vérifiant sa destination.
Cas de recette à reproduire
Exemple fictif : ces données ne décrivent aucun client ni résultat réel.
Voir les données du cas
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}Décision attendue
Exemple fictif : une archive compressée de 2 Mo produit 600 Mo alors que le budget est 100 Mo. Arrêtez dès le dépassement des octets réellement écrits et gardez le lot hors publication, même si les premiers fichiers semblent valides.
Python — tarfile extraction filters and further verification
Une archive petite ou un filtre d’extraction garantit-il un résultat sûr ?
Non. Une petite archive peut produire beaucoup de données. Les filtres doivent être complétés par des limites de ressources, des règles de chemins et la validation des fichiers obtenus.
Référence primaire : Python — tarfile extraction filters and further verification. Méthode connexe : consulter le guide pratique.
Erreurs API : types, statuts et preuves
Inclure les erreurs dans les tests de contrat
Une nouvelle URI de type, une extension retirée ou un statut modifié peut changer le comportement d’un consommateur. Les exemples d’échec font partie du contrat au même titre que les réponses réussies.
- Rejouer les anciens clients sur les refus représentatifs.
- Vérifier la tolérance aux extensions inconnues et aux textes localisés.
- Documenter la migration d’une identité de problème et les usages réellement observés.
Explorer les types de problèmes et les huit réponses fictives →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5