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 :

Panneau de brassage en fibre optique, photographié par Patrick Finnegan en 2002.

Panneau de brassage en fibre optique, photographié par Patrick Finnegan en 2002. Photo de contexte documentaire ; elle ne représente pas une mission ou un équipement d’Alexis Roux ZG. © Patrick Finnegan · Source · CC BY 2.0. Redimensionnement et conversion WebP ; affichage recadré.

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.

Situations et arbitrages

Situations types pour préparer un contrôle. Elles ne décrivent pas des missions ou observations réalisées.

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.

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.