Comment normaliser les données de 84 API en un seul schéma (et le tester par contrats)

Normaliser les avis provenant de 84 plateformes, dont 59 avec une API officielle et 25 sans : un seul schéma, des identifiants stables, la déduplication et des tests de contrat conformes à une spécification OpenAPI.

Francisco Garcia Domene

Francisco Garcia Domene

16 November 2026

Comment normaliser les données de 84 API en un seul schéma (et le tester par contrats)

Apidog pour les entreprises

Déploiement sur site

SSO & RBAC

Conforme SOC 2

Découvrir Apidog Enterprise

Je dirige Prisma Reviews, une petite API qui renvoie les avis clients de 84 plateformes dans un format JSON unique. Cet article ne porte pas sur le produit. Il porte sur trois problèmes d'ingénierie qui ont occupé la majeure partie de notre temps : concevoir un schéma qui s'adapte à des sources aux formes très différentes, garantir la stabilité des identifiants pour qu'un même avis n'apparaisse jamais deux fois, et tester le contrat pour qu'un changement en amont ne casse pas silencieusement les clients en aval.

Une précision d'abord, car elle conditionne tout le reste : toutes les sources d'avis ne sont pas des API. Sur nos 84 sources, 59 disposent d'une API officielle. Les 25 autres n'en ont pas, et nous lisons à la place leurs pages publiques ou leurs flux.

Toutes les sources ne sont pas des API

Chaque plateforme de notre configuration a trois propriétés : comment une entreprise s'y connecte, si nous pouvons publier une réponse, et comment les nouveaux avis nous parviennent. En classant les 84 sources selon notre méthode de lecture, on obtient quatre groupes :

GroupeSourcesExemples
API officielle, identifiants propres de l'entreprise ou OAuth50Google Business Profile (accès en attente), App Store, Google Play, Trustpilot (accès en attente), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, gestionnaires de propriétés comme Hostaway et Guesty
API publique officielle, sans identifiants d'entreprise9Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator
Pas d'API : page publique ou flux3Shopify App Store (page HTML des avis), WordPress.org (flux RSS des avis), Apple Podcasts (flux public des avis)
Pas d'API : fournisseur de données payant22Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable
Diagramme en barres des 84 sources d'avis : 50 avec une API officielle utilisant les identifiants de l'entreprise, 9 avec une API publique, 3 lues depuis une page publique ou un flux, 22 lues via un fournisseur de données payant

Ces groupes diffèrent sur des points qui se répercutent dans la conception de l'API :

Certaines plateformes apparaissent deux fois. Les avis Airbnb et Booking.com peuvent provenir d'une page publique (lecture seule), ou de l'API officielle d'un gestionnaire de propriétés, qui autorise les réponses. C'est la raison d'être de l'un des champs présentés plus bas.

Un seul schéma pour toutes

Chaque avis, quelle que soit la source, a les mêmes 14 champs, et tous sont toujours présents. Quand une plateforme ne nous fournit pas une information, le champ vaut null, il n'est jamais absent. Une clé manquante et un null signifient la même chose pour un humain, mais pas pour un client typé, et « toujours présent » est facile à tester.

{
  "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
  "platform": "google",
  "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
  "rating": 4,
  "title": null,
  "text": "Great flat white, a bit slow at lunchtime.",
  "author": "Marta G.",
  "language": "en",
  "url": null,
  "source": null,
  "created_at": "2026-10-19T12:41:07.000Z",
  "updated_at": "2026-10-19T12:41:07.000Z",
  "deleted_at": null,
  "reply": null
}

rating est un entier de 1 à 5, ou null. Booking.com note sur 10, nous divisons donc par deux, arrondissons et bornons à 1-5. Steam n'a pas d'étoiles, seulement « recommandé » ou « non recommandé », que nous mappons sur 5 et 1. Certaines sources permettent un avis sans note du tout, et dans ce cas le champ vaut null. Nous n'écrivons jamais 0 : cela ressemble à une vraie note et tire les moyennes vers le bas.

text et title peuvent être null. Les avis avec seule une note sont courants sur les app stores, et seules certaines plateformes ont des titres. Nous n'en inventons pas un à partir de la première phrase.

url a une signification précise sur les plateformes en lecture seule. Quand nous ne pouvons pas publier une réponse, url indique où l'entreprise peut y répondre à la main. Si un client tente quand même de répondre, l'erreur contient la même URL.

source existe à cause des agrégateurs. Viator renvoie des avis rédigés sur Viator et sur Tripadvisor. Un gestionnaire de propriétés renvoie des avis Airbnb, Booking.com et Vrbo via une seule connexion. platform indique par quelle connexion l'avis est passé ; source indique sur quel site il a été rédigé.

created_at et updated_at sont distincts parce que les gens modifient leurs avis. Un avis d'une étoile modifié qui devient un avis de quatre étoiles doit être une mise à jour, pas une nouvelle ligne.

reply est un objet avec un statut, pas une chaîne. Le statut est published, queued, failed ou unknown. Le dernier mérite une explication. Parfois, la requête vers la plateforme part et aucune réponse ne revient, et la plateforme n'offre aucun moyen de relire la réponse. Réessayer pourrait publier deux fois la même réponse, au nom de l'entreprise. Nous nous arrêtons donc, marquons unknown, et demandons au client de vérifier la plateforme avant de republier. Un statut qui dit « on ne sait pas » est plus utile qu'une supposition.

Diagramme des statuts de réponse : une réponse est acceptée avec 202 et mise en file d'attente, puis se termine en published, failed ou unknown

Les limites de longueur des réponses sont vérifiées par plateforme avant la mise en file : 4 096 octets sur Google Business Profile, 350 caractères sur Google Play, 80 sur eBay. Un emoji compte un caractère mais quatre octets, nous comptons donc les points de code pour les limites en caractères et les octets pour les limites en octets.

Identifiants stables et déduplication

Les doublons sont le bug que les clients remarquent en premier. Notre règle est simple : chaque connecteur doit renvoyer l'identifiant propre de la plateforme pour chaque avis, et la base de données a un index unique sur (location_id, external_id). Une seconde synchronisation d'un même avis est une mise à jour, jamais une insertion. Les établissements fonctionnent de la même manière, avec un index unique sur (connection_id, external_id).

La difficulté, c'est que « l'identifiant propre de la plateforme » n'existe pas toujours :

Les clients ne voient jamais les identifiants de plateforme comme clés primaires. Ils reçoivent nos propres identifiants, avec un préfixe de type et un corps ordonné par le temps (rev_01KJ…, loc_01KJ…, req_01KJ…). Le préfixe rend un identifiant égaré évident dans les logs, et l'ordre aide à la pagination : le curseur encode l'horodatage et l'identifiant du dernier élément, si bien qu'une frontière de page reste stable pendant que de nouveaux avis arrivent.

Reconnexion. Une entreprise déconnecte un compte et le reconnecte une semaine plus tard. Créer de nouveaux établissements dupliquerait chaque avis. À la place, un établissement déconnecté depuis moins de 30 jours avec le même identifiant externe est réactivé : mêmes identifiants, aucun avis dupliqué.

Suppressions. Un avis retiré de la plateforme cesse simplement d'apparaître. Rien ne vous le signale. Pour 60 des 84 sources, nous pouvons lire l'historique complet, nous le relisons donc périodiquement (tous les 25 jours pour Google Business Profile, dont les conditions ne nous permettent pas de conserver du contenu non confirmé plus de 30 jours ; chaque semaine pour la plupart des autres) et marquons avec deleted_at les avis que la plateforme ne renvoie plus, plus un webhook review.deleted. La sauvegarde essentielle : si une lecture s'est arrêtée prématurément, à cause d'un timeout ou d'une limite de pages, nous ne marquons rien. Considérer « je ne l'ai pas vu » comme « il a disparu » supprimerait de vrais avis. Google Play est exclu en raison de sa fenêtre de sept jours.

Tests de contrat contre la spécification OpenAPI

Le contrat est un document OpenAPI 3.1 avec 18 chemins, 30 schémas et 9 événements webhook. Deux types de tests le maintiennent honnête.

Le premier est bon marché et s'exécute à chaque commit : les énumérations de la spécification doivent correspondre exactement au code. Les identifiants de plateforme dans la spécification doivent être égaux à la liste de la configuration des plateformes, et les événements webhook de la spécification doivent être égaux aux types d'événements que le code peut émettre. Les clients générés rejettent les valeurs d'énumération qu'ils ne connaissent pas ; une plateforme ajoutée au code mais pas à la spécification casserait donc ces clients dès leur première synchronisation.

Le second est un mode de test. Les clés API existent en deux sortes, pk_live_… et pk_test_…, sur le même serveur. Une clé de test aiguille chaque plateforme vers un connecteur de test : des établissements et des avis d'exemple déterministes qui ressemblent aux vrais (un café sur Google, une application sur l'App Store, un hôtel sur Booking.com), des réponses qui sont acceptées et jamais publiées nulle part, et sur les plateformes en lecture seule un url sur chaque avis, car la documentation en promet un. N'importe qui peut exécuter le contrat entier, chemins d'écriture compris, sans toucher à un vrai compte.

Les exemples ci-dessous sont ceux de la spécification, avec des URL remplacées par example.com. Une requête de liste :

GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…

renvoie l'avis montré plus haut dans data, plus un next_cursor. Une réponse vers une plateforme qui prend en charge les réponses est acceptée avec 202, et l'avis revient avec sa réponse en file d'attente (autres champs omis) :

POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply
Authorization: Bearer pk_test_…
Content-Type: application/json

{ "text": "Thanks Marta! We have added a second barista at lunch." }
{
  "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
  "platform": "google",
  "reply": {
    "text": "Thanks Marta! We have added a second barista at lunch.",
    "created_at": null,
    "status": "queued",
    "error": null
  }
}

Les cas intéressants sont les échecs. Chaque erreur a la même forme (type, code, message, retryable, request_id, docs_url), et certains codes ajoutent des champs sur lesquels un client peut agir. Répondre à un avis Yelp renvoie 422 :

{
  "error": {
    "type": "invalid_request_error",
    "code": "reply_not_supported",
    "message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid",
    "retryable": false,
    "request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N",
    "docs_url": "https://example.com/docs/errors#reply_not_supported",
    "platform": "yelp",
    "url": "https://example.com/biz/example-cafe-madrid"
  }
}

Une réponse dépassant la limite de la plateforme renvoie aussi 422, avec code: "reply_too_long", platform: "google_play" et max_length: 350. Les clients doivent faire un branchement sur code, jamais sur message : le message est destiné aux humains et peut changer.

La même forme tient en trafic réel. Voici une réponse de production à une requête sans clé (en-têtes élagués, URL de la documentation remplacée) :

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S

{"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}}

Le request_id du corps correspond à l'en-tête Request-Id. Pour chaque opération, nous vérifions le code de statut, la validation du corps contre son schéma (les 14 champs d'avis présents, types nullables là où déclarés), la forme d'erreur sur chaque réponse non-2xx, et les en-têtes Request-Id et de limite de débit en cas de succès.

Exécuter les mêmes vérifications avec Apidog CLI

Ces mêmes vérifications fonctionnent sur toute API livrant un fichier OpenAPI. Apidog CLI importe la spécification, et un agent de code tel que Claude Code écrit et exécute les cas de test. Configurez-le une fois :

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Terminal montrant la configuration d'Apidog CLI et la commande apidog import chargeant un fichier OpenAPI dans un projet

Donnez ensuite un seul prompt à l'agent :

Import ./openapi.json into Apidog project <projectId>. Create test cases for the
list reviews and reply endpoints that assert the status code, that the body
validates against its schema with all 14 review fields present, and that the
Request-Id header is set. Add a case that replies to a Yelp review and expects
422 with code reply_not_supported. Run them against the test environment and
summarize any failures.

L'agent importe la spécification, lit le schéma des cas de test, valide sa charge utile, crée le cas et l'exécute :

apidog import --project <projectId> --format openapi --file ./openapi.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit
Terminal montrant Apidog CLI validant un fichier de cas de test, créant le cas de test et l'exécutant avec les rapporteurs CLI et JUnit

Le rapporteur junit écrit un fichier que votre CI sait lire, la même exécution peut donc servir de garde-fou à chaque pull request. Le guide CI/CD d'Apidog CLI couvre la configuration du pipeline.

Enseignements

Modélisez « dispose d'une API » et « peut répondre » comme des propriétés distinctes. Atlassian et Microsoft montrent qu'une API peut exister sans pour autant accepter les réponses. Un seul indicateur pour les deux promettrait des réponses que nous ne pouvons pas livrer.

Prévoyez l'état de réponse unknown avant que la première réponse parte. Un état qui admet l'incertitude coûte une valeur d'énumération ; une réponse publique dupliquée coûte la confiance d'un client.

Ne partez pas du principe qu'un identifiant de plateforme existe ou reste stable. Notez, pour chaque connecteur, d'où vient l'identifiant et ce qui pourrait le changer.

Testez la spécification contre le code, pas seulement le code contre la spécification. Le test des énumérations fait une dizaine de lignes, et il protège contre la défaillance qui nuit le plus aux clients générés.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API