Diff de réponse API : comparer des payloads JSON d'API en ligne
Collez la réponse attendue à gauche, la réponse réellement reçue à droite, et voyez chaque champ qui a changé. Conçu pour le travail backend, QA et intégration. Rien ne quitte votre navigateur.
Ce qu'est cet outil de diff de réponse API
Un outil gratuit, intégré au navigateur, pour comparer deux corps de réponse HTTP d'API. Collez le JSON obtenu depuis staging à gauche, le JSON obtenu depuis la production à droite, et les différences sont surlignées caractère par caractère. Le texte ne quitte jamais votre machine, ce qui est important parce que les vraies réponses d'API contiennent régulièrement des adresses email de clients, des tokens de session, des identifiants utilisateur internes, et d'autres choses que vous ne voulez pas envoyer à un site de diff tiers.
Il est conçu pour le moment où un test d'intégration instable casse en CI, et que vous avez une capture Postman d'une réponse fonctionnelle sur votre portable et un log CI d'une réponse cassée depuis le runner de build. Monter un contract test Pact complet pour une investigation ponctuelle est démesuré. Deux panneaux de texte, un diff, et vous pouvez généralement isoler le problème à un seul champ en moins d'une minute.
En dessous, le moteur de diff est le même que celui qui fait tourner notre outil compare-json. Nous l'avons simplement mis en scène pour le workflow de tests d'API. Si vos réponses sont en XML ou en enveloppes SOAP, notre page compare-xml les gère. Si vous comparez du texte libre comme un log de webhook ou une piste d'audit, notre outil compare-text est la bonne surface.
En quoi un diff de réponse API aide vraiment
Un diff de réponse API se situe dans l'espace entre deux idées de tests proches mais distinctes. Le diff de schéma OpenAPI 3.1 vous dit ce que votre contrat déclare avoir changé : un nouveau champ optionnel, une propriété renommée, un enum plus strict. Le snapshot testing (snapshots Jest, snapshots Vitest, pytest-snapshot) vous dit ce que votre code a produit par rapport à un fixture sauvegardé. Cet outil se place côté runtime. Vous lui donnez deux corps de réponse réels et il vous montre chaque octet qui diffère, peu importe que le schéma autorise ou non le changement, ou que votre fixture de snapshot soit à jour ou non.
Pourquoi est-ce utile ? Parce que les bugs qui font le plus mal en intégration REST ne sont pas des violations de schéma. Ce sont des dérives subtiles : un sérialiseur qui a discrètement changé une date d'ISO-8601 à un timestamp Unix après une montée de version Jackson, un schéma Marshmallow qui s'est mis à émettre null au lieu d'omettre un champ absent, un ViewSet DRF qui s'est mis à envelopper le payload dans un data après un changement de middleware. La spec OpenAPI n'a pas changé. Le snapshot n'a pas été mis à jour. Les tests sont passés en isolation. L'intégration a cassé. Un diff de corps de réponse attrape tous ces cas parce qu'il ne se soucie pas du contrat ; il se soucie des octets.
Les champs volatiles sont la principale chose à surveiller. Timestamps, request IDs, trace IDs, UUIDs générés serveur, et curseurs de pagination différeront entre deux captures du même endpoint, même quand rien de significatif n'a changé. Le bon réflexe est de normaliser avant le diff : remplacez les timestamps par un placeholder, supprimez les trace IDs, triez les arrays là où l'ordre n'est pas contractuel. Des outils comme Pact gèrent ça avec des matchers ; dans cet outil vous le gérez en éditant les panneaux. Ça prend dix secondes et ça supprime le bruit de fond.
Comment faire un diff de réponse API en trois étapes
Deux panneaux de texte, un diff. Pas de login, pas d'upload, pas de proxy à câbler.
- 1
Capturez la première réponse
Appelez l'endpoint avec curl, httpie, Postman, Insomnia, ou ce que votre équipe utilise. curl -s https://api.example.com/v1/users/123 | jq est une bonne base parce que jq formate joliment le JSON, ce qui rend le diff bien plus facile à lire. Copiez le corps (le JSON seul, pas les en-têtes) et collez-le dans le panneau de gauche. Si vous tirez d'un log CI, retirez le préfixe de timestamp que la plupart des loggers ajoutent pour que le diff porte sur le payload réel.
- 2
Capturez la deuxième réponse
Appelez la source de comparaison : l'autre environnement, l'autre version d'API, l'autre fournisseur. Même forme de capture, même étape de pretty-print. Collez-la dans le panneau de droite. Si une capture vient d'un fixture enregistré (vcrpy, pollyjs, MSW, nock) et l'autre est en direct, normalisez d'abord les champs volatiles évidents : nettoyez le request_id, remplacez les timestamps par une constante, et retirez les en-têtes de trace qui auraient fui dans le corps. Le diff restant est le vrai signal.
- 3
Lisez les différences surlignées
Les suppressions apparaissent en barré rouge à gauche ; les insertions en vert à droite. Les compteurs de changements dans chaque en-tête vous disent combien d'éditions distinctes le diff a trouvées. Concentrez-vous d'abord sur trois choses : changements de chaînes de status, clés ajoutées ou absentes, et changements de type de valeur (string vers number, objet vers null). Ces trois catégories couvrent presque toute régression d'API réelle. Les changements de format et d'ordre sont généralement du bruit, sauf si votre consumer en dépend.
Quand un diff de réponse API est le bon choix
Reproduire un test d'intégration instable
Un test passe en local et casse en CI. Vous avez la réponse capturée par votre Postman local et celle capturée par l'agent de build CI (la plupart des systèmes CI peuvent dumper request/response avec un flag verbose). Collez les deux dans l'outil de diff. Neuf fois sur dix la différence est environnementale : un feature flag différent, un fixture obsolète, un décalage de fuseau horaire sur le runner. La dixième fois c'est un vrai bug, et vous venez de le localiser sur un champ précis.
Valider un fixture face à une réponse fraîche
Votre dépôt contient un fichier de fixture committé qui mocke une API tierce pour les tests. Le fournisseur upstream vient de livrer une nouvelle version mineure. Appelez l'endpoint en direct avec curl, collez cette réponse à côté de votre fixture, et vous voyez exactement quels champs ont dérivé. C'est la version manuelle de ce que les outils de replay style VCR automatisent. Utile quand vous voulez mettre à jour un fixture sans réenregistrer toute votre suite de tests.
Vérifier la rétrocompatibilité entre versions d'API
Vous êtes sur le point de livrer la v2 d'une API interne. Un client v1 existe encore en production. Appelez à la fois /v1/orders/42 et /v2/orders/42 et faites le diff des réponses. Tout champ supprimé, toute clé renommée, tout changement de type de valeur est un breaking change pour le client v1. Tout nouveau champ est additif et sans risque. C'est la version du pauvre d'un contract test consumer-driven ; ça ne passe pas l'échelle sur des dizaines d'endpoints, mais pour une vérification rapide sur un ou deux ça marche.
Repérer une régression de sérialiseur
Votre équipe a fait monter Jackson, Marshmallow, DRF, ou une couche de sérialisation similaire. Les tests passent. Puis un consumer downstream signale que son parser s'étouffe. Capturez la même réponse d'endpoint sur l'ancienne branche et la nouvelle et faites le diff. Trouvailles courantes : un format de date est passé de 2026-05-09T10:00:00Z à un timestamp Unix, des décimales ont perdu leurs zéros de fin, un enum s'est mis à se sérialiser en entier au lieu de string, ou des champs null sont apparus dans le payload alors qu'ils étaient auparavant omis.
Comparer des payloads de webhook entre deux fournisseurs ou versions
Les webhooks Stripe V1 et V2 du même type d'événement se ressemblent presque et ne le sont pas du tout. Pareil pour les payloads d'événements webhook GitHub entre versions d'API, et pour les abonnements aux événements Slack entre scopes. Collez un payload exemple de chaque dans l'outil de diff pour voir les champs renommés, les objets imbriqués déplacés, et les nouveaux blocs de métadonnées. C'est plus rapide que de lire les deux pages de doc fournisseur côte à côte, surtout quand la doc passe sous silence quels champs apparaissent vraiment en pratique.
Déboguer le classique "ça marche en staging, cassé en prod"
Le mal de tête classique du déploiement. La même requête client renvoie un JSON subtilement différent depuis staging et la production. Capturez les deux, collez les deux, et la différence est généralement un flag de config, un feature gate manquant, ou une réponse mise en cache obsolète. Ça s'applique aussi bien au debug multi-régions (us-east-1 vs eu-west-1 renvoyant des données différentes), aux problèmes de cache CDN (Cloudflare a mis en cache un corps obsolète), et au lag de réplica de lecture où une écriture ne s'est pas propagée partout.
Cas limites du diff de réponse API à connaître
Les cas où un diff de corps de réponse n'est pas d'accord avec ce que diraient votre framework de tests, votre outil OpenAPI, ou vos yeux. Vaut le coup de les survoler avant de supposer que le diff a trouvé un vrai bug.
| Topic | What this tool does |
|---|
| Champs volatiles (timestamps, IDs) | created_at, updated_at, request_id, trace_id, les UUIDs générés serveur et les curseurs de pagination différeront toujours entre deux captures. Normalisez-les avec jq 'del(...)', remplacez par une constante, ou retirez-les simplement avant le diff. Le signal qui vous intéresse vraiment est ailleurs. |
|---|
| null vs clé absente | {"foo": null} et {} sont différents en JSON, et beaucoup de sérialiseurs (Marshmallow, Jackson, System.Text.Json) ont des réglages qui basculent entre les deux. Le diff fera ressortir cela. Certains clients les traitent comme équivalents et d'autres non ; la bonne réponse est ce que fait votre consumer, c'est pourquoi c'est une source fréquente de régression après une montée de version de sérialiseur. |
|---|
| Ordre des clés | Le RFC 8259 définit les objets JSON comme non ordonnés. Deux réponses sémantiquement identiques avec un ordre de clés différent apparaîtront ici comme un diff parce que la comparaison textuelle est sensible à l'ordre. Pré-triez les deux côtés avec jq --sort-keys si vous voulez un diff insensible à l'ordre. Attention au rare consumer qui dépend de l'ordre (certains flux de signature, certains parsers legacy). |
|---|
| Ordre des arrays | Les arrays en JSON sont ordonnés, mais beaucoup d'APIs renvoient des arrays dont l'ordre n'est pas vraiment contractuel : une liste de permissions, une liste de feature flags, une liste d'abonnements à des webhooks. Un diff signalera un array réordonné comme un changement même si aucun consumer n'y tient. Si réordonner est sans impact dans votre domaine, triez les deux côtés sur une clé stable avant le diff. |
|---|
| Strictesse de JSON.parse | Le diff traite votre entrée comme du texte opaque. Si une de vos captures a une virgule traînante, une clé non quotée, ou un commentaire (tous illégaux en JSON strict), il fera quand même le diff mais ce sera plus bruité que nécessaire. Faites passer les deux captures par jq . d'abord pour reformater et rejeter l'entrée invalide. jq utilise un parser RFC 8259 strict. |
|---|
| Enveloppes de réponse (data envelope vs plat) | Beaucoup d'APIs enveloppent les payloads dans un {"data": ...}, parfois en ajoutant meta, links, ou included à côté (JSON:API et similaires). Une migration de plat vers enveloppé (ou l'inverse) est un breaking change qui apparaît immédiatement dans un diff mais facile à manquer dans une revue de schéma parce que l'enregistrement sous-jacent semble identique. |
|---|
| Changements de curseur de pagination | La pagination par curseur utilise des tokens opaques (next_cursor, after, page_token) conçus pour changer à chaque appel. Ils apparaîtront toujours comme un diff. Retirez-les avant comparaison, ou comparez seulement le contenu de l'array data et ignorez complètement le bloc de pagination. |
|---|
| Formats de réponse d'erreur | Les corps d'erreur sont le Far West. Certaines APIs renvoient un {"error": "..."} plat, d'autres renvoient RFC 7807 Problem Details avec type, title, status, detail, instance, et d'autres renvoient une forme propre au fournisseur. Une migration vers RFC 7807 depuis une forme propriétaire produira un gros diff qui est en majorité une amélioration ; une migration dans l'autre sens est une régression à attraper tôt. |
|---|
Diff de réponse API : questions fréquentes
En quoi est-ce différent de la fonction de diff intégrée à Postman ?
Postman a une vue de comparaison de réponse dans son Collection Runner et une fonction Visualize pour les réponses individuelles. Les deux sont bonnes si vous vivez dans Postman et que vos réponses sont déjà sauvegardées comme entrées d'historique Postman. Cet outil est agnostique au fournisseur. Vous pouvez coller depuis Postman, Insomnia, curl, httpie, un log CI, un snippet Stack Overflow, ou un message Slack d'un collègue. Pas de compte, pas de workspace, pas de sync. Pour des comparaisons ponctuelles entre outils, c'est plus rapide. Pour des tests d'API partagés en équipe dans une seule plateforme, la fonction de Postman fait l'affaire.
Comment gérer les champs volatiles comme les timestamps et request IDs ?
Le geste pragmatique est de normaliser avant le diff. Ouvrez les deux collés dans les panneaux, puis éditez directement les champs volatiles : remplacez les timestamps par une chaîne constante, retirez les valeurs request_id et trace_id, supprimez les curseurs de pagination qui changent à chaque appel. Le diff ne surligne que les différences restantes, qui sont celles qui comptent vraiment. Pour des comparaisons répétées du même endpoint, vous pouvez aussi faire passer la réponse par jq avec un filtre delete (jq 'del(.meta.request_id)') avant de coller.
En quoi est-ce différent d'un diff de schéma OpenAPI ?
Le diff de schéma compare des contrats : il vous dit que POST /orders a ajouté un champ optionnel discount_code, ou que l'enum status a gagné une nouvelle valeur. Les outils conscients d'OpenAPI comme oasdiff ou Spectral le font bien. Cet outil compare les corps de réponse réels. Les deux sont complémentaires. Le diff de schéma attrape les changements de contrat ; le diff de réponse attrape la dérive entre le contrat et la réalité, là où se cachent les bugs de sérialisation, les écarts d'environnement et les fixtures obsolètes.
Gère-t-il les grosses réponses ?
En pratique oui, jusqu'à quelques milliers de lignes de JSON formaté de chaque côté. Au-delà, le diff au caractère avec nettoyage sémantique ralentit parce qu'il tourne dans votre navigateur, pas sur un serveur. Pour des payloads très gros (pensez à un dump paginé de 10 000 enregistrements), la bonne approche est de découper la réponse en morceaux plus petits par enregistrement ou par clé de premier niveau et de faire le diff de chaque morceau séparément. Ou de lancer un diff structurel en ligne de commande avec jd ou diff <(jq . a.json) <(jq . b.json) pour la vitesse pure.
Fonctionne-t-il pour les réponses XML ou SOAP ?
Pas directement. Cette page est calibrée pour JSON, qui est ce que la plupart des payloads modernes REST et webhook utilisent. Si vous devez faire un diff de XML, d'enveloppes SOAP, de RSS, ou de configuration style POM, notre outil compare-xml est la bonne surface ; il gère l'indentation et le formatage des namespaces correctement. Pour des corps de réponse bruts qui mélangent en-têtes et corps, ou pour des APIs en texte brut (certains systèmes legacy renvoient encore text/plain), compare-text fait le travail sans tenter d'imposer une structure.
Préserve-t-il l'ordre des clés ou les trie-t-il ?
Il préserve l'ordre des clés que vous collez. Les objets JSON sont formellement non ordonnés selon le RFC 8259, donc deux réponses sémantiquement identiques avec des clés dans un ordre différent apparaîtront comme un diff dans cet outil. Si vous voulez ignorer l'ordre, normalisez les deux côtés d'abord en passant par jq --sort-keys ou équivalent. La plupart des clients ne dépendent pas de l'ordre des clés, donc la normalisation par clés triées est un défaut sûr pour comparer des réponses ; sachez que certains consumers legacy (anciens ponts XML-vers-JSON, certains flux de signature numérique) y tiennent.
Confidentialité et pourquoi c'est important pour les réponses d'API
Les payloads de réponse d'API contiennent régulièrement des choses que vous ne voulez pas laisser fuiter. Adresses email de clients. Identifiants utilisateur internes. Tokens de session. Tokens bearer d'auth qui ont fini dans un champ du corps par erreur. IDs client Stripe. Secrets de webhook. Champs PII comme noms, adresses, et numéros de téléphone. Coller un de ces payloads dans un service de diff hébergé dans le cloud est en soi un événement de traitement de données, et selon votre secteur cela peut violer vos contrôles SOC 2, vos accords de traitement de données RGPD, ou vos Business Associate Agreements HIPAA. Cet outil tourne entièrement dans votre navigateur. Rien n'est envoyé, journalisé, ou transmis à un service tiers. Le diff, le surlignage et le rendu s'exécutent tous sur votre machine. Vérifier le claim est direct : ouvrez les DevTools de votre navigateur, allez dans l'onglet Network, collez les deux réponses, et regardez. Aucune requête sortante au moment de la comparaison. Pour des conseils plus larges de design et de sécurité d'API, les bonnes pratiques de design d'API de Microsoft sont une référence solide.