Évaluer le changement du point de vue du client
Le tableau propose une grille de revue, pas une garantie universelle. Un champ ajouté peut perturber un lecteur strict ; une valeur d’énumération nouvelle peut casser un traitement exhaustif. Inventoriez les clients, leurs bibliothèques et leurs hypothèses avant de classer le changement.
| Changement | Risque à vérifier | Preuve attendue |
|---|---|---|
| Retirer ou renommer un champ | Lecture devenue impossible | Migration explicite et tests clients. |
| Ajouter un champ facultatif | Lecteur strict ou conflit de nom | Test des consommateurs existants. |
| Ajouter une valeur en réponse | Traitement exhaustif incomplet | Comportement prévu pour une valeur inconnue. |
| Changer une valeur par défaut | Résultat métier différent | Comparaison des scénarios sans valeur explicite. |
Organiser la coexistence
- Décrivez ancienne et nouvelle formes, valeurs par défaut, erreurs, pagination et règles d’autorisation. Exécutez des tests de contrat avec des cas représentatifs des consommateurs.
- Choisissez une stratégie explicite de sélection de version. Distinguez version du service et version du document OpenAPI ; vérifiez les caches et les passerelles.
- Publiez un calendrier, un guide de migration et un point de contact. Suivez l’usage réel des versions avec une télémétrie proportionnée et prévoyez un retour arrière compatible avec les données.
Distinguer dépréciation et arrêt
Deprecation signale qu’une ressource est dépréciée ; Sunset peut annoncer quand elle devrait devenir indisponible. Ces en-têtes complètent l’accompagnement sans migrer les clients. Ne retirez une version qu’après examen des consommateurs restants, de leurs obligations et de la procédure de reprise.
Références primaires
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
Pour approfondir
Versioning : décider selon l’impact consommateur
Ajouter un numéro à l’URL ne préserve pas à lui seul les clients existants. Un changement de type, de valeur attendue, de comportement ou de réponse d’erreur peut être incompatible même si le chemin reste identique.
- Inventorier les clients actifs et leurs usages observés.
- Tester les anciennes versions de clients contre le nouveau contrat.
- Publier une période de coexistence et vérifier l’usage avant retrait.
Référence primaire : IETF RFC 9457 — Problem Details for HTTP APIs. Méthode connexe : consulter le guide pratique.
Tâches API asynchrones : suivre l’état, reprendre et annuler
Ne pas confondre requête acceptée, traitement démarré et résultat final d’une opération longue.
- Compte, opération et identifiant
- Transition, heure et source
- Résultat, erreur ou effets restants
- Même tâche retrouvée, droits vérifiés et issue ou incertitude explicitée
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
{
"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"
}
]
}Décision attendue
Une réponse 200 au suivi ne signifie pas que le traitement est terminé. Après une demande d’annulation, seule l’issue confirmée permet de conclure.
Une annulation demandée trop tard
Scénario fictif : même tâche J-42, temps en secondes depuis la soumission. Les noms d’état relèvent du contrat de cet exemple ; HTTP ne les impose pas.
| Instant | Réponse et état | Conclusion autorisée |
|---|---|---|
| +0 s | HTTP 202 · pending | Accepté pour traitement ; aucun résultat final confirmé. |
| +5 s | HTTP 200 · running | La lecture du statut a réussi ; la tâche travaille encore. |
| +6 s | HTTP 200 · cancel_requested | La demande d’arrêt est enregistrée ; l’annulation reste à confirmer. |
| +7 s | HTTP 200 · succeeded | Le traitement a gagné la course. Présenter la réussite observée et vérifier les effets ; ne pas annoncer « annulé ». |
202 signifie-t-il que la tâche est terminée ?
Non. Le traitement n’est pas nécessairement achevé. Le client doit pouvoir consulter une issue faisant foi.
Référence primaire : MDN — 202 Accepted. Méthode connexe : consulter le guide pratique.
Mise à jour logicielle : vérifier un changement de signataire
Décider si un livrable signé correspond toujours au producteur, au processus et à la version approuvés.
- Avant de lire le nouveau paquet, consignez producteur, clé ou identité de certificat, émetteur et processus de construction autorisés. Reliez ces attentes au logiciel concerné et à un canal de confirmation déjà fiable. Le paquet à vérifier ne doit pas définir seul sa propre politique d’acceptation.
- Rapprochez l’empreinte du fichier reçu de l’objet décrit par l’attestation. Vérifiez la signature avec les racines de confiance prévues, puis identité, constructeur et paramètres attendus. Une signature cryptographiquement valide provenant d’une autre identité ne satisfait pas la politique du service.
- Testez une rotation annoncée, un émetteur inattendu, une signature absente et un fichier différent. Gardez le livrable en attente lorsque la nouvelle identité n’est pas confirmée. Enregistrez l’approbation du changement et une solution de retour ; une signature ne prouve pas l’absence de vulnérabilité.
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
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}Décision attendue
Exemple fictif : l’empreinte correspond et la signature est valide, mais le signataire observé diffère du signataire approuvé. L’installation reste en attente d’une confirmation indépendante du changement.
Référence primaire : SLSA v1.2 — Verifying artifacts. Méthode connexe : consulter le guide pratique.
API : dépréciation et retrait
Préparer le retrait au-delà du numéro de version
Une version publiée ne dit pas quand les consommateurs doivent migrer. Relier les annonces de dépréciation, les dates de retrait et les tests des clients existants.
- Distinguer Deprecation, Sunset et les liens vers les politiques.
- Vérifier que Sunset n’est pas antérieur à Deprecation lorsque les deux dates sont fournies.
- Mesurer les consommateurs restants et valider le remplacement avant une bascule.
Comparer les annonces de dépréciation et de retrait →
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