Guides pratiques approfondis

Interroger une API publique et conserver une extraction vérifiable

Définir la requête, contrôler la pagination, distinguer erreur et absence et conserver la réponse brute avant toute transformation.

Mise à jour :

Ordinateur et tablette présentant une réponse API schématique et une ligne à vérifier avant import. Scène illustrative.

Illustration générée par IA

Comment reproduire une extraction sans lui attribuer une fausse exhaustivité ?

Une API fournit une réponse à une requête, dans un schéma et à un instant donnés. Elle ne garantit pas que l’utilisateur a demandé toute la base ni que les données n’ont pas changé entre deux appels. Le protocole conserve la sélection, les états techniques et les données reçues, puis sépare ce relevé de l’analyse.

  1. Choisir le bon accès

    Ouvrez la documentation officielle. Vérifiez la version, le périmètre, les conditions d’usage, l’authentification et les limites de volume. Pour une base entière, cherchez un export officiel : une API de recherche peut limiter l’exhaustivité.

  2. Définir une petite requête

    Notez endpoint, méthode, paramètres, filtres et ordre de tri. Commencez par quelques lignes. Privilégiez un identifiant stable à un nom ambigu. Ne publiez jamais une clé ou un jeton dans le journal de requête.

  3. Contrôler la réponse

    Consignez statut HTTP, heure de réception, format et message d’erreur. Vérifiez les champs et leurs unités. Un HTTP 200 peut contenir une réponse vide, une erreur métier ou un schéma différent ; inspectez le corps reçu.

  4. Suivre la pagination

    Lisez le total annoncé et le mécanisme de page ou de curseur. Comptez lignes reçues et identifiants uniques, documentez les doublons et gardez la condition d’arrêt. Une base qui évolue pendant la collecte peut modifier les résultats entre pages.

  5. Conserver et transformer séparément

    Gardez la réponse brute et son empreinte, puis documentez nettoyage, filtres et conversions. Associez chaque sortie à l’extraction d’origine. Si des données personnelles ou des secrets sont présents, ne les publiez pas dans le journal public.

  6. Traiter les changements

    Sur une erreur 429 ou une indisponibilité, respectez les indications de reprise plutôt que de relancer sans limite. Une nouvelle extraction est une nouvelle observation : comparez aussi schéma, paramètres et périmètre.

Exemples de requêtes minimales

Ces adresses illustrent la syntaxe ; disponibilité, authentification et conditions sont à contrôler dans la documentation.

Atelier de lecture

Un journal de revalidation, pas une nouvelle extraction vide

Les échanges HTTP DEMO sont fictifs. Ce volet ne contacte aucun serveur et n’effectue aucune relance.

Données et traces fictives pour apprendre : aucun résultat présenté ici ne provient d’un service interrogé en direct.

Séparer la copie, sa validation et une limite de requêtes

Le client du scénario conserve une représentation pour area=A avec son ETag. La politique fictive borne les relances à deux essais. Elle ne garantit pas la disponibilité du service.

  1. Conserver la première copie

    Échange fictif
    GET area=A → 200, corps et ETag "demo-v1"
    État conservé
    Corps associé à la requête exacte
    Décision du scénario
    Garder filtres, version et représentation ensemble.
  2. Revalider la même sélection

    Échange fictif
    Même requête avec If-None-Match → 304 sans corps
    État conservé
    La copie correspondante est disponible
    Décision du scénario
    Réutiliser cette copie ; ne pas enregistrer une extraction de zéro ligne.
  3. Changer de sélection

    Échange fictif
    Nouvelle requête area=B
    État conservé
    La copie de A ne documente pas B
    Décision du scénario
    Traiter la sélection séparément, même si le texte d’un ETag se ressemble.
  4. Atteindre une limite

    Échange fictif
    429 ; Retry-After: 15
    État conservé
    Échec de cette tentative, pas résultat zéro
    Décision du scénario
    Attendre selon l’indication ; à la borne de deux essais, arrêter et consigner.

Quel journal distingue bien les états de collecte ?

Ouvrir chaque proposition pour comparer son diagnostic. Plusieurs contrôles peuvent rester nécessaires.

304 : nouvelle sélection vide

Non. Dans ce scénario, la copie de la même sélection reste la pièce utilisée. Le corps absent ne devient pas un tableau vide.

Copier les données de A dans l’extraction de B

Non. Cela change silencieusement le périmètre des observations. Les paramètres font partie de la trace.

Conserver la référence à la copie de A et noter séparément l’arrêt sur limite

Oui. Le journal doit permettre de retrouver les données utilisées et les tentatives qui n’ont fourni aucune nouvelle extraction.

Trace fictive du client

Sélection : GET /demo?area=A
Copie : corps conservé ; ETag="demo-v1"
Condition : If-None-Match="demo-v1"
Réponse : 304 ; référence à la copie A
Autre tentative : 429 ; Retry-After=15 secondes
Politique DEMO : deux essais maximum, puis arrêt
Droits de republication : à vérifier séparément

La borne de deux essais appartient à cet exemple, pas aux RFC. Sans copie exploitable, ne pas inventer de contenu ; préparer une nouvelle récupération conforme à la politique du service.

Documentation des règles, distincte des exemples fictifs

Comparer avec les autres situations et exercices

Une seule page téléchargée

Le fichier contient des résultats mais pas forcément toute la sélection. Vérifiez total, taille de page et prochain curseur avant de publier un décompte.

Valeur absente remplacée par zéro

Gardez la différence entre null, champ absent, liste vide et zéro. Une conversion automatique peut modifier une moyenne ou un classement.

Même requête, nouveau résultat

Eurostat documente une base contenant les versions les plus récentes. Conservez l’extraction datée si vous devez reproduire un calcul ancien.

Exercice corrigé

Un statut 200 avec une erreur applicative

Exemple fictif : les valeurs et documents servent à apprendre la méthode, sans décrire un organisme réel.

Le contrat de cette API fictive exige success=true avant traitement. Examinez séparément réponse HTTP, état applicatif et présence des résultats.

Si le tableau dépasse l’écran, faites-le défiler horizontalement ; les flèches du clavier fonctionnent lorsque la zone est sélectionnée.

Données de départ
ÉlémentInformation observée
Statut HTTP200
Indicateur applicatifsuccess=false
Message reçuMessage : quota atteint
Tableau de résultatsAucun tableau fourni

À vous de vérifier

  1. Contrôler statut HTTP et indicateur applicatif séparément.
  2. Vérifier la présence du schéma attendu.
  3. Conserver l’erreur sans publier de faux effectif.
Lire le corrigé

Corrigé et décision

Le transport a répondu, mais la collecte n’a pas réussi selon ce contrat. Aucun effectif nul n’est établi. Classer l’extraction en échec et suivre la règle de reprise documentée ; ne pas fabriquer un tableau vide pour continuer un calcul.

Si le cas change

Si une réponse réussie contient réellement un tableau vide, le zéro peut être établi pour la requête et le périmètre explicités. Rejouer avec success=true mais un corps JSON tronqué avant la fin : le statut et le drapeau ne suffisent toujours pas. Refuser ce lot incomplet, conserver le point de reprise et vérifier qu’aucune valeur partielle n’a remplacé la dernière extraction validée.

Trace à conserver

Garder requête expurgée des secrets, statut, erreur, contrat et état de reprise.

Référence documentaire : IETF — RFC 9110, 200 OK · Consultée le

REPÈRES DOCUMENTÉS

Wikidata : « truthy » sélectionne un rang, pas une vérité certifiée

Le mot truthy nomme une projection technique des déclarations. Pour une propriété d’une entité, la présence de déclarations de rang préféré écarte les déclarations normales de cette projection. À défaut, les déclarations normales sont retenues. Cette règle ne constitue ni un vote automatique sur les sources ni une recherche de la date la plus récente.

Wikidata : « truthy » sélectionne un rang, pas une vérité certifiée
RepèreValeur ou formeCe que cela désigne
PreferredRankPreferredLes déclarations préférées sont retenues ensemble lorsqu’il en existe pour la propriété de cette entité. Le rang préféré ne garantit donc pas une valeur unique.
NormalRankNormalLes déclarations normales alimentent la projection seulement en l’absence de rang préféré pour ce couple entité-propriété. Plusieurs valeurs normales peuvent être légitimes.
DeprecatedRankDeprecatedLes déclarations dépréciées ne sont pas retenues dans la projection truthy. Elles peuvent rester présentes dans les déclarations complètes pour documenter une erreur ou une valeur rejetée.
wdt:Best non-deprecated rankLe chemin direct utilise les meilleurs rangs non dépréciés et ne transporte pas les qualificatifs. Une valeur ainsi extraite n’est pas automatiquement actuelle, complète ou étayée.
wikibase:BestRankFull statement selectionCe type permet de sélectionner les déclarations de meilleur rang en conservant leurs nœuds. Il reste possible de lire leurs qualificatifs et références au lieu d’aplatir immédiatement la valeur.
ScopeEntity + propertyLa règle s’applique par propriété et par entité. Une préférence sur la population ne règle pas le choix d’une date de fondation, d’un nom ou d’une autre propriété.

À retenir pour le dossier

Si toutes les déclarations sont dépréciées, ne pas inventer un retour automatique vers ces valeurs. Pour étudier un désaccord ou une histoire, lire les déclarations complètes et conserver les rangs. Une valeur absente d’une requête directe peut être filtrée par le rang ; elle n’est pas nécessairement absente de la base.

Peut-on interpréter une valeur wdt: comme la valeur la plus récente ?

Non. Le rang et le qualificatif temporel répondent à deux mécanismes distincts. Examiner le point dans le temps et la politique de rang avant d’écrire « dernière valeur » ; plusieurs déclarations préférées peuvent coexister.

Documentation primaire

Documentation consultée le .

REPÈRES DOCUMENTÉS

API Banque mondiale : trois dates et une unité à retrouver

Une réponse JSON n’est pas seulement une valeur. L’extrait réel ci-dessous concerne la densité finlandaise en 2023. Son en-tête annonce une mise à jour WDI le 8 octobre 2026 ; sa récupération ici date du 23 octobre. Ces trois dates répondent à trois questions différentes.

date2023lastupdated2026-10-08extracted2026-10-23
API Banque mondiale : trois dates et une unité à retrouver
RepèreValeur ou formeCe que cela désigne
date2023Année de l’observation. Elle ne devient pas 2026 parce que la requête a été exécutée en 2026.
lastupdated2026-10-08Date de mise à jour indiquée par l’en-tête de la source. Elle n’atteste pas à elle seule une révision de cette valeur particulière.
extracted2026-10-23Date de constitution de l’extrait local ; elle ne remplace ni la période observée ni la date de source.
unit""L’unité est vide dans cet enregistrement. La définition de EN.POP.DNST précise pourtant des personnes par km² de terres : vide ne veut pas dire sans dimension.
decimal / value0 / 18.3705454665088Le champ decimal vaut zéro alors que value contient des décimales. Conserver la valeur fournie ; ne pas lire ce champ comme une marge d’erreur.
pages / total1 / 4Les quatre observations tiennent sur une seule page de réponse. Une autre requête peut être paginée : vérifier pages et total avant de conclure que la collecte est complète.

Requête exacte · densité

https://api.worldbank.org/v2/country/FRA;DEU;ESP;FIN/indicator/EN.POP.DNST?date=2023&format=json&per_page=100

En-tête et observation FIN conservés

[
    {
        "page": 1,
        "pages": 1,
        "per_page": 100,
        "total": 4,
        "sourceid": "2",
        "lastupdated": "2026-10-08"
    },
    [
        {
            "indicator": {
                "id": "EN.POP.DNST",
                "value": "Population density (people per sq. km of land area)"
            },
            "country": {
                "id": "FI",
                "value": "Finland"
            },
            "countryiso3code": "FIN",
            "date": "2023",
            "value": 18.3705454665088,
            "unit": "",
            "obs_status": "",
            "decimal": 0
        }
    ]
]

À retenir pour le dossier

L’extrait est une photographie datée de l’API, sans mise à jour automatique au chargement. Un code de pays commun ne prouve pas que toutes les séries ont une couverture territoriale identique. Pour reproduire l’analyse, conserver la requête complète, les définitions et les valeurs absentes, sans transformer null en zéro.

Documentation primaire

Documentation consultée le .

REPÈRES DOCUMENTÉS

Paramètres de formulaire : garder les espaces, les signes + et les doublons

Une liste de paramètres est une suite ordonnée de couples nom-valeur. Elle peut contenir deux fois le même nom. L’outil applique le format application/x-www-form-urlencoded avec URLSearchParams à deux valeurs sur une ligne, puis relit le résultat ; il ne soumet aucun formulaire.

tag → C++ & IAtag → ététag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9getAll("tag") → ["C++ & IA", "été"]
Paramètres de formulaire : garder les espaces, les signes + et les doublons
RepèreValeur ou formeCe que cela désigne
U+0020+Un espace U+0020 est sérialisé en + dans ce format. Ce n’est pas une règle universelle pour toutes les parties d’une URL.
+%2BUn signe + qui appartient réellement à la valeur devient %2B. Coller C++ directement dans une chaîne déjà encodée ferait relire ses deux + comme des espaces.
&%26Une esperluette à l’intérieur d’une valeur devient %26. Elle ne crée alors pas de paramètre supplémentaire.
=%3DLe signe = à l’intérieur d’une valeur devient %3D ; le séparateur structurel entre le nom et la valeur reste =.
été%C3%A9t%C3%A9Les caractères non ASCII sont encodés à partir d’UTF-8. Le pourcentage représente des octets, pas un nombre de lettres affichées.
append / get / getAll / setordered pairsappend conserve une nouvelle occurrence. get renvoie la première valeur ; getAll renvoie toutes les valeurs dans leur ordre. set remplace la première et retire les autres occurrences de ce nom.

Explorer deux paramètres de même nom

Deux valeurs de démonstration, calculées dans cette page.

Deux couples conservés dans leur ordre.

Sérialisation

tag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9

Valeurs relues avec getAll

["C++ & IA","été"]

Première valeur avec get

"C++ & IA"

À retenir pour le dossier

Encoder n’est ni chiffrer ni nettoyer du HTML. Cette démonstration ne simule pas la sélection des contrôles d’un formulaire, ses fichiers multipart ou sa normalisation des retours à la ligne. Le serveur doit décider explicitement comment traiter les paramètres répétés ; les convertir trop tôt en objet peut perdre des valeurs.

Documentation primaire

Documentation consultée le .

Preuve à conserver

  • Service, version d’API, endpoint et paramètres sans secrets.
  • Horodatage, statut HTTP, format, nombre de pages et condition d’arrêt.
  • Réponses brutes, identifiants uniques et empreinte des fichiers.
  • Transformations, unités, exclusions, sortie et limites d’exhaustivité.

Références officielles

Fiches de sources associées

Protocoles connexes

Points à vérifier avant de conclure

  • La sélection peut-elle être reconstituée sans utiliser un secret ?
  • Le nombre publié tient-il compte des pages et doublons ?
  • Les réponses d’origine sont-elles séparées des données nettoyées ?

Questions fréquentes

HTTP 200 prouve-t-il que la collecte est complète ?

Non. Contrôlez le corps, les filtres, le total et la pagination.

Faut-il toujours collecter toute la base ?

Non. Choisissez le périmètre utile. Un petit extrait identifié vaut mieux qu’une collecte dont les limites ne sont pas connues.

Une empreinte garantit-elle les chiffres ?

Elle permet de comparer les octets du fichier conservé. La méthode et la qualité des données nécessitent leurs propres contrôles.

Comment reprendre une collecte interrompue ?

Conserver la dernière étape confirmée, les paramètres et les références de continuation. La reprise doit vérifier les doublons et les changements possibles des données plutôt que supposer une simple addition des réponses.

REPÈRES DOCUMENTÉS

Écriture HTTP : vérifier la version avant de remplacer un document

Deux personnes peuvent lire la même version puis envoyer des corrections différentes. Une précondition permet au serveur de refuser une écriture fondée sur une ancienne représentation. Les cas ci-dessous sont fictifs : v1 et v2 sont des étiquettes pédagogiques, pas des versions relevées sur un service.

GET → "v1"ETag: "v2"PUT → 412If-Match: "v1" ≠ ETag: "v2"

Lecture → modification concurrente → écriture refusée : exemple fictif.

Écriture HTTP : vérifier la version avant de remplacer un document
RepèreValeur ou formeCe que cela désigne
PUT · If-Match: "v1"ETag: "v2" → 412La copie a changé depuis la lecture. Sur cette requête PUT, la comparaison forte échoue : ne pas remplacer la version courante. Relire puis examiner les différences avant de décider.
PUT · If-Match: "v2"ETag: "v2" → ✓Les étiquettes fortes concordent : cette précondition autorise la poursuite du traitement. Elle ne garantit ni une réponse 200 ni la réussite des autres contrôles.
PUT · If-Match: W/"v2"ETag: "v2" → 412Même texte opaque, mais préfixe faible : If-Match demande une comparaison forte et échoue. Retirer W/ côté client ne rend pas le validateur fort.
PUT · If-None-Match: *Présente → 412 / Absente → ✓Pour une écriture, l’astérisque demande qu’aucune représentation courante n’existe. Si elle existe, la condition échoue ; si elle est absente, le traitement peut continuer.
GET · If-None-Match: W/"v2"ETag: "v2" → 304Pour GET ou HEAD, If-None-Match utilise une comparaison faible. Une concordance conduit à 304 : utiliser la copie conservée, sans recevoir un nouveau corps.
428Precondition RequiredLe serveur exige une requête conditionnelle. Ce refus pour condition manquante est distinct de 412, qui indique une condition évaluée à faux. Une réponse 428 ne doit pas être mise en cache.

Essayer une précondition

Modifiez la méthode, l’état et la condition. Saisissez une étiquette entre guillemets, une liste séparée par des virgules ou * seul. Le contrôle reste dans votre navigateur. Avec * ou une représentation absente, l’ETag actuel n’est pas utilisé.

412 : condition non satisfaite. Ne pas exécuter l’opération demandée.

Simulation pédagogique locale : aucune requête API n’est envoyée et aucune donnée n’est enregistrée.

À retenir pour le dossier

L’exercice évalue une seule précondition sur une ressource, avant l’action. Il suppose une requête par ailleurs recevable et écarte le cas particulier d’une opération déjà exécutée avec succès. Authentification, autorisation, validation du document et règles métier restent à vérifier. Une API doit contrôler et appliquer la modification de manière atomique pour réellement éviter les écrasements.

Documentation primaire

Documentation consultée le .

APPROFONDISSEMENT / PRATIQUE

Conserver une requête reproductible

Une API fournit des données utiles, mais le résultat dépend de paramètres et de pagination. La collecte doit conserver la requête complète et les conditions nécessaires pour comprendre la réponse.

Mis à jour le .

Vérifications prioritaires

Relever URL, paramètres, statut, format et pagination. Contrôler les filtres, les limites de volume et les erreurs renvoyées sans exposer de secret dans les journaux.

Pièges d’interprétation

Une réponse réussie peut ne contenir qu’une page de résultats. Répéter la requête plus tard peut fournir un état différent si les données ont évolué.

Document de travail à conserver

Le journal de collecte associe requête, date, réponse conservée, couverture et limite. Il précise comment reprendre ou vérifier l’extraction.