API et automatisation
Écarts décimaux dans une API : comment les examiner sans modifier le contrat
Un exemple de suivi d’une valeur et deux cas documentés aident à localiser les écarts de précision sans présumer de leur cause ni modifier le contrat.
Ce que montrent les cas documentés
Un écart visible dans une valeur décimale ne suffit pas à conclure que JSON en est la cause ni à déterminer à quel moment il est apparu. Les sources disponibles décrivent deux situations précises : elles sont utiles pour orienter une enquête, mais ne définissent pas une règle générale applicable à toutes les API.
Esri a consigné un écart de précision après le séparateur décimal entre les résultats d’une requête ArcGIS REST API présentés aux formats HTML et JSON. La portée du cas est décrite dans le signalement Esri BUG-000117969 : https://support.esri.com/es-es/bug/the-query-results-in-the-rest-api-in-html-and-json-form-bug-000117969. Ce signalement permet d’affirmer que cet écart a été observé dans ce cas précis, mais pas d’en déterminer ici la cause ni de le généraliser à d’autres services.
IBM explique comment éviter les erreurs d’arithmétique décimale dans Db2 for z/OS. L’extrait disponible mentionne la possibilité d’une erreur de division dans des instructions SQL statiques et la règle DEC31. Consultez l’article d’IBM sur les erreurs d’arithmétique décimale pour vérifier le contexte : https://www.ibm.com/docs/es/db2-for-zos/13.0.0?topic=statement-avoiding-decimal-arithmetic-errors. Il ne s’agit pas d’une explication générale de la représentation des décimales en JSON.
Lors de votre enquête, distinguez donc trois éléments : l’écart observé, l’étape du parcours où vous le détectez et l’explication qu’il vous reste à vérifier. Cette distinction évite de transformer un symptôme précis en conclusion sur l’ensemble du système.
- Esri documente un écart entre deux formats de réponse dans un cas précis.
- IBM traite un problème spécifique d’arithmétique décimale dans Db2 for z/OS.
- Aucun de ces cas ne définit un format numérique universel pour les autres API.
Exemple : suivre le même champ du début à la fin
L’exemple suivant est un modèle de diagnostic, pas un résultat publié ni une recommandation de format. Supposons que vous testiez un champ appelé montant et que vous consigniez la valeur d’entrée 123.4500. Au cours d’une exécution, vous observez 123.4500 dans la requête, puis 123.45 à une étape du traitement et 123.45 dans la réponse. Cet exemple montre uniquement comment noter un écart textuel ; il ne permet pas de conclure si la valeur interprétée a changé, s’il y a eu arrondi ni quel composant a produit l’observation.
Effectuez ce suivi pour le cas réel qui vous préoccupe. Notez le nom du champ et recopiez ce que vous observez à chaque frontière à laquelle vous avez accès : la donnée préparée par l’appelant de l’API, la requête effectivement envoyée, la donnée reçue par le service si vous pouvez l’observer, toute valeur intermédiaire pertinente et la réponse reçue. Si vous n’avez accès qu’à la requête et à la réponse, consignez ces deux extrémités et précisez que vous n’avez pas observé les étapes internes.
Pour rendre l’exemple reproductible, conservez avec l’échantillon les étapes qui le produisent : l’opération exécutée, l’entrée utilisée et la réponse obtenue. Si vous comparez deux exécutions, ne modifiez qu’une seule condition pertinente à la fois et notez laquelle. Ne changez pas simultanément la valeur, l’opération et la représentation : il serait alors plus difficile de savoir quel écart vous comparez.
Comparez les échantillons capturés, et pas seulement un écran ou un rapport susceptible de présenter les données différemment. Si l’écart apparaît uniquement dans une vue, notez-le comme tel et essayez également d’obtenir la requête ou la réponse correspondante. Consignez le premier point où vous pouvez l’observer ; il s’agit d’un constat pratique, pas d’une preuve automatique de la cause interne.
- Champ : montant. Valeur d’entrée observée : 123.4500.
- Traitement : consignez la valeur observée ou indiquez que cette étape n’est pas visible.
- Sortie : recopiez la réponse reçue et précisez si l’écart était déjà présent auparavant.
- Si vous utilisez des valeurs fictives pour préparer un test, indiquez que le cas est illustratif.
Comment préparer une vérification utile
Avant d’exécuter le test, précisez ce que vous cherchez à savoir. Par exemple : « À quel moment de ce parcours l’écart entre la valeur que j’envoie et celle que je reçois apparaît-il pour la première fois ? » Cette question est plus vérifiable que « Pourquoi JSON modifie-t-il les décimales ? », qui présuppose une cause qui n’a pas encore été démontrée.
Utilisez un échantillon réduit qui reproduit le cas et conservez la même entrée lors des comparaisons. Identifiez le point de terminaison et l’opération concernés, puis notez si la réponse a été obtenue au cours de la même exécution ou d’un test distinct. Si le problème ne se produit qu’avec une certaine opération, consignez cette condition au lieu de la présenter comme un comportement général.
Comparez ensuite chaque observation à la précédente : requête préparée et requête envoyée ; requête envoyée et réponse reçue ; et, lorsque c’est possible, données d’entrée et de sortie de l’étape examinée. Si vous n’avez pas accès à une étape, ne la complétez pas par une supposition. Écrivez « non observé » et poursuivez avec les frontières que vous pouvez vérifier.
Répéter les mêmes étapes peut aider à déterminer si vous observez à nouveau l’écart dans ces conditions. Si le résultat change, consignez-le également. Aucun des deux résultats ne permet à lui seul d’identifier une cause : ils servent à décrire le cas et à préparer la vérification suivante.
- Définissez une question précise avant d’exécuter le test.
- Conservez le même échantillon et consignez toute condition modifiée.
- Distinguez les données observées, les étapes inaccessibles et les hypothèses à vérifier.
- Conservez suffisamment d’étapes pour qu’une autre personne puisse reproduire le cas.
Interpréter les constats sans modifier le contrat
Un test de ce type peut montrer que deux observations diffèrent et circonscrire l’endroit où l’écart est détecté. Il ne permet pas, à lui seul, d’établir le comportement interne qui l’a produit. Vous pourriez examiner une différence dans l’échantillon envoyé, dans une étape de traitement observée ou dans la manière dont le résultat est présenté ; considérez ces éléments comme des possibilités à vérifier, et non comme des explications confirmées.
Ne convertissez pas le champ en chaîne de caractères, ne changez pas son échelle et ne l’arrondissez pas par précaution sans avoir confirmé le contrat applicable. Les éléments disponibles ne justifient aucune recommandation générale entre nombres, chaînes de caractères ou unités mineures, et ne définissent aucune règle universelle d’échelle ou d’arrondi. Un changement de représentation peut modifier l’interprétation du champ selon le contrat ; vérifiez d’abord ce qu’il autorise et ce que le champ signifie.
Si la documentation du point de terminaison ne précise pas la représentation ou le résultat attendu, posez la question au responsable du service en lui communiquant le cas reproductible. Demandez une réponse spécifique au champ, à l’opération et au point de terminaison concernés. Une définition précise permet de déterminer quoi comparer ; l’absence de définition ne permet pas d’inférer une règle applicable à d’autres services.
- Considérez le premier point où vous voyez l’écart comme une limite d’observation, et non comme une cause confirmée.
- Consultez le contrat avant de changer le type, l’échelle ou l’arrondi.
- Formulez la question en suspens au fournisseur de manière précise et reproductible.
Partager le cas et ses limites
Lorsque vous demandez de l’aide, partagez un échantillon minimal qui démontre l’écart, ainsi que les étapes nécessaires pour le reproduire. Indiquez la valeur attendue, ce que vous avez observé et les étapes où vous avez pu effectuer des mesures. Si une étape n’était pas visible, précisez-le explicitement. La personne qui examine le cas pourra ainsi distinguer les données d’entrée, le résultat et les questions encore sans réponse.
Avant d’enregistrer ou de partager des traces, supprimez les identifiants et les données personnelles ou sensibles qui ne sont pas nécessaires au diagnostic. Limitez les personnes pouvant accéder aux échantillons et la durée de leur conservation en fonction des besoins de l’enquête.
Enfin, veillez à ce que votre conclusion reste proportionnée au test : vous pouvez signaler un écart reproductible dans une intégration précise et décrire où vous l’avez détecté. Ne généralisez pas ce résultat à des valeurs, des opérations ou des services que vous n’avez pas testés. Les cas Esri et Db2 permettent de consulter des situations documentées, mais ne remplacent pas la définition du comportement attendu de votre API.
- Incluez l’échantillon minimal, les étapes et la réponse observée.
- Séparez les résultats reproductibles des hypothèses en suspens.
- Masquez les informations sensibles et limitez l’accès aux traces.
Questions fréquentes
Un écart décimal dans la réponse prouve-t-il que JSON en est la cause ?
Non. Esri documente un écart de précision entre des résultats HTML et JSON dans un cas d’ArcGIS REST API, mais ce précédent n’établit pas une cause universelle pour les autres API.
Dois-je toujours envoyer les décimales sous forme de chaînes de caractères ?
Les éléments présentés ici ne permettent pas de recommander un format général. Vérifiez dans le contrat du point de terminaison quelle représentation est acceptée et comment le champ doit être interprété.
Que permet de conclure l’exemple de suivi ?
Il permet de consigner des observations à différentes étapes et d’indiquer où vous avez détecté un écart pour la première fois. À lui seul, il ne démontre pas la cause interne.
Quelles informations est-il utile d’envoyer au fournisseur ?
Un échantillon minimal expurgé, les étapes permettant de reproduire le cas, l’écart observé et les étapes que vous avez pu examiner. Indiquez également quel comportement attendu doit être clarifié.
Sources et lectures
Documentation consultée pour préparer cet article.
- Cómo evitar errores de aritmética decimal - Db2 — IBM
- BUG-000117969 for ArcGIS GIS Server — Esri Support
Découvrez Apification
Articles associés
API et automatisation
Webhooks ou polling pour détecter les changements de fichiers : comment choisir
Comparez les notifications et les interrogations périodiques pour choisir une stratégie de détection des changements adaptée à la latence, au volume et aux capacités de reprise dont vous avez besoin.
API et automatisation
Webhooks reçus dans le désordre : éviter qu’un ancien événement ne rétablisse l’état d’un fichier
L’heure de réception ne suffit pas à établir l’ordre des changements. Découvrez comment vérifier le contrat du webhook et réconcilier l’état du fichier selon des critères vérifiables.
API et automatisation
Comment identifier les fichiers dans une API sans dépendre de noms ou de chemins susceptibles de changer
Concevez des références moins sensibles aux renommages et aux déplacements : examinez le contrat OpenAPI, conservez les correspondances et testez les cas susceptibles de rompre la synchronisation.