Crossref
https://api.crossref.org/works?rows=1
DocumentationGuides pratiques approfondis
Définir la requête, contrôler la pagination, distinguer erreur et absence et conserver la réponse brute avant toute transformation.
Mise à jour :

Illustration générée par IA
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.
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é.
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.
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.
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.
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.
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.
Ces adresses illustrent la syntaxe ; disponibilité, authentification et conditions sont à contrôler dans la documentation.
Atelier de lecture
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.
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.
Ouvrir chaque proposition pour comparer son diagnostic. Plusieurs contrôles peuvent rester nécessaires.
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.
Non. Cela change silencieusement le périmètre des observations. Les paramètres font partie de la trace.
Oui. Le journal doit permettre de retrouver les données utilisées et les tentatives qui n’ont fourni aucune nouvelle extraction.
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.
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.
Gardez la différence entre null, champ absent, liste vide et zéro. Une conversion automatique peut modifier une moyenne ou un classement.
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é
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.
| Élément | Information observée |
|---|---|
| Statut HTTP | 200 |
| Indicateur applicatif | success=false |
| Message reçu | Message : quota atteint |
| Tableau de résultats | Aucun tableau fourni |
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 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.
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
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.
| Repère | Valeur ou forme | Ce que cela désigne |
|---|---|---|
| PreferredRank | Preferred | Les 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. |
| NormalRank | Normal | Les 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. |
| DeprecatedRank | Deprecated | Les 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 rank | Le 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:BestRank | Full statement selection | Ce 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. |
| Scope | Entity + property | La 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é. |
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.
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 consultée le .
REPÈRES DOCUMENTÉS
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.
| Repère | Valeur ou forme | Ce que cela désigne |
|---|---|---|
| date | 2023 | Année de l’observation. Elle ne devient pas 2026 parce que la requête a été exécutée en 2026. |
| lastupdated | 2026-10-08 | Date 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. |
| extracted | 2026-10-23 | Date 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 / value | 0 / 18.3705454665088 | Le 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 / total | 1 / 4 | Les 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. |
https://api.worldbank.org/v2/country/FRA;DEU;ESP;FIN/indicator/EN.POP.DNST?date=2023&format=json&per_page=100
[
{
"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
}
]
]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 consultée le .
REPÈRES DOCUMENTÉS
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.
| Repère | Valeur ou forme | Ce 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. |
| + | %2B | Un 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. |
| & | %26 | Une esperluette à l’intérieur d’une valeur devient %26. Elle ne crée alors pas de paramètre supplémentaire. |
| = | %3D | Le signe = à l’intérieur d’une valeur devient %3D ; le séparateur structurel entre le nom et la valeur reste =. |
| été | %C3%A9t%C3%A9 | Les 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 / set | ordered pairs | append 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. |
Deux valeurs de démonstration, calculées dans cette page.
Deux couples conservés dans leur ordre.
tag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9
["C++ & IA","été"]
"C++ & IA"
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 consultée le .
Non. Contrôlez le corps, les filtres, le total et la pagination.
Non. Choisissez le périmètre utile. Un petit extrait identifié vaut mieux qu’une collecte dont les limites ne sont pas connues.
Elle permet de comparer les octets du fichier conservé. La méthode et la qualité des données nécessitent leurs propres contrôles.
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
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.
Lecture → modification concurrente → écriture refusée : exemple fictif.
| Repère | Valeur ou forme | Ce que cela désigne |
|---|---|---|
| PUT · If-Match: "v1" | ETag: "v2" → 412 | La 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" → 412 | Mê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" → 304 | Pour GET ou HEAD, If-None-Match utilise une comparaison faible. Une concordance conduit à 304 : utiliser la copie conservée, sans recevoir un nouveau corps. |
| 428 | Precondition Required | Le 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. |
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.
Condition satisfaite : poursuivre les contrôles et le traitement normal. Aucun statut de succès n’est déduit.412 : condition non satisfaite. Ne pas exécuter l’opération demandée.304 : condition non satisfaite pour GET/HEAD. Réutiliser la copie conservée.Syntaxe invalide : utilisez une ou plusieurs étiquettes HTTP entre guillemets, ou * seul. L’ETag actuel doit être une seule étiquette lorsque la représentation existe.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 consultée le .
APPROFONDISSEMENT / PRATIQUE
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 .
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.
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é.
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.