Au-delà du modèle : pourquoi les data scientists doivent adopter les API et la documentation des API
1. Introduction
à l’intersection de divers domaines – statistiques, programmation, IA – la capacité à transmettre des méthodologies et des informations complexes devient cruciale. Ainsi, la capacité de gérer des concepts API complets est essentielle pour une communication efficace au sein de l’équipe.
Premièrement, cela favorise la collaboration entre les membres de l’équipe et les parties prenantes. Les projets de Data Science (DS) impliquent souvent des équipes multidisciplinaires composées non seulement de spécialistes des données, mais également de développeurs de logiciels, d’analystes commerciaux, de chefs de projet, etc. Des API bien documentées servent de pont entre eux, permettant à ces divers groupes de comprendre et d’utiliser correctement les modèles et outils DS.
Deuxièmement, une documentation API de haute qualité améliore la reproductibilité et peut réduire le temps d’intégration des nouveaux arrivants. Dans DS, où les modèles et les analyses doivent être validés et répliqués, une documentation claire des API garantit que d’autres peuvent suivre les mêmes processus, utiliser les mêmes données et obtenir des résultats cohérents. Ceci est particulièrement important pour développer une prise de décision basée sur les données.
Enfin, à mesure que la science des données est de plus en plus intégrée aux stratégies commerciales, des API bien documentées peuvent améliorer l’évolutivité des solutions de données et simplifier le processus de travail avec les données. Par exemple, les API peuvent jouer un rôle important dans la collecte de données pour les projets, permettant un prototypage et un développement rapides d’applications reposant sur des informations à jour. En tirant parti des API pour la collecte de données provenant de sources telles que les pays REST (voir cas 6.1), les data scientists peuvent se concentrer sur l’analyse plutôt que sur l’acquisition de données.
Dans cet article, nous allons :
- Explorez brièvement ce qu’est une API et son objectif dans le développement de logiciels.
- Rencontrez les principaux composants de l’API REST.
- Décrivez les formats les plus courants et fournissez des cas pratiques d’appels et de réponses API.
- Résumez à quoi devrait ressembler une bonne documentation d’API, avec des informations sur les points de terminaison, les paramètres et les réponses.
2. Qu’est-ce que l’API
Une API (Application Programming Interface) comprend un ensemble de méthodes par lesquelles différents programmes communiquent entre eux et échangent des données. Il s’agit essentiellement d’un intermédiaire qui permet aux applications, appareils, serveurs et autres systèmes d’échanger des informations, tout en masquant les processus au sein de chaque système.
Imaginez une bibliothèque avec une grande collection de livres et un bibliothécaire qui sait où trouver le livre exact dont un certain lecteur a besoin. Ici, nous pouvons désigner le bibliothécaire comme une API qui simplifie le processus d’accès à l’information, évitant aux lecteurs (notre « frontend ») de perdre du temps à chercher dans l’ensemble du catalogue de livres (notre « backend »), leur permettant de se concentrer uniquement sur leur demande spécifique. De plus, si les lecteurs ont besoin d’un autre livre, ils peuvent répéter le processus d’envoi de la demande à l’API.
Cette analogie met en évidence le rôle de l’API en tant qu’intermédiaire entre l’utilisateur et la source de données, offrant un accès pratique et efficace à l’information.
Un cas particulier d’API est une API REST qui suit les concepts de l’architecture REST (REpresentational State Transfer). Les API REST sont considérées comme la norme de l’industrie car elles sont légères, flexibles et utilisent des formats de données courants tels que JSON ou XML.
3. Composants de l’API REST
Chacun des composants de l’API REST ci-dessous joue un rôle essentiel dans l’organisation des interactions client-serveur.
3.1. Ressources
Une ressource est toute entité accessible via l’API. Chaque ressource possède un identifiant unique (URI), par exemple :
https://api.thecatapi.com/v1/images/search?size=med
Ici, images est une collection d’images de chats provenant de la page Web de l’API Cat [1]et search?size=med est le filtre pour afficher uniquement les images de taille moyenne.
3.2. Méthodes HTTP
Les méthodes HTTP sont utilisées pour interagir avec les ressources :
- GET — récupère des données sur une ressource ;
- POST — crée une nouvelle ressource ;
- PUT – mettre à jour une ressource ;
- PATCH — mise à jour partielle d’une ressource ;
- DELETE — supprime une ressource.
3.3. Demandes et réponses
Les données sont échangées entre le client et le serveur via des requêtes et des réponses HTTP. Dans la plupart des cas, le format JSON est utilisé car il est facile à lire et pris en charge par la grande majorité des langages de programmation.
3.4. En-têtes HTTP
Les en-têtes sont utilisés pour transmettre des informations supplémentaires, telles que le type de contenu (Content-Type) ou des paramètres d’authentification (Authorization).
3.5. Codes de réponse HTTP
Chaque requête HTTP reçoit une réponse avec un code d’état spécifique :
- 200 OK — demande réussie ;
- 201 Créé : ressource créée avec succès ;
- 400 Bad Request — erreur de demande du client ;
- 401 Non autorisé — manque de droits d’accès ;
- 404 Not Found — ressource introuvable ;
- 500 Erreur interne du serveur : erreur côté serveur.
4. Clients API
Clients API comme Postman ou Bruno [2] simplifiez l’interaction avec l’API en fournissant un espace de travail dédié à l’envoi de demandes et à la gestion des réponses. Au lieu d’utiliser des outils de ligne de commande ou d’écrire du code comme nous l’avons fait dans le cas 6.1, ces agents offrent des interfaces visuelles et des fonctionnalités d’automatisation qui accélèrent les flux de travail.
Ainsi, dans le cas 6.2, nous envisagerons d’utiliser Bruno pour interagir avec la page web JokeAPI [3]. L’utilisation de Bruno simplifie le processus complexe d’interaction entre différents systèmes logiciels. Sans Bruno et les autres clients API, les développeurs devraient construire manuellement chaque requête HTTP et traiter chaque réponse brute à partir de zéro.
5. Conseils pour créer une bonne documentation API
La création d’une documentation API efficace est cruciale pour garantir que les utilisateurs peuvent facilement comprendre et utiliser votre API. Voici quelques conseils clés à garder à l’esprit :
5.1. Privilégiez la simplicité, la clarté et la cohérence
Évitez le jargon technique et la terminologie incohérente. Utilisez plutôt un langage suffisamment direct et simple, facile à suivre. Si nécessaire, établissez un guide de style pour maintenir l’uniformité tout au long de votre documentation. Ici, vous pouvez indiquer les principales règles utilisées tout au long de votre documentation, par exemple comment formater les extraits de code, les instantanés, le ton de voix préféré, etc.
5.2. Inclure des détails complets
Une documentation complète de l’API doit englober plusieurs éléments essentiels, en particulier une page typique avec la méthode API comprend :
- Une brève description (1 à 2 phrases) qui décrivent clairement l’objectif principal du point final.
- La syntaxe de la requête: Un aperçu de l’appel API.
- Méthodes d’authentification: Détaillez les processus d’authentification nécessaires pour accéder à l’API en toute sécurité.
- Paramètres et types de données : Spécifiez les paramètres requis et leurs types de données correspondants pour les demandes.
- Exemples de demandes: Fournissez des exemples de requêtes correctes et de requêtes comportant une erreur pour illustrer comment utiliser l’API efficacement.
6. Cas pratiques
Cas 6.1 : Faire une requête à une API RESTful à l’aide de Python
La collecte de données au niveau national est essentielle pour comprendre les tendances mondiales, régionales ou nationales, permettant ainsi une prise de décision éclairée aux gouvernements, aux entreprises et aux chercheurs individuels. Lorsque vous travaillez avec des données nationales comme le site Web REST Countries [4]les data scientists peuvent obtenir des informations sur les pays via une API RESTful pour récupérer efficacement la zone, la population et les démonymes sans extraire manuellement des tonnes de données Web. Le code ci-dessous récupère et affiche des données sur les pays d’Amérique centrale :
import requests
import json
url = 'https://restcountries.com/v3.1/subregion/Central America/?fields=name,area,population,demonyms'
response = requests.get(url)
jdata = response.json()
formatted_json = json.dumps(jdata, indent=4)
print(formatted_json)Les régions géographiques sont définies à l’aide de la méthodologie de l’ONU [5]. Vous pouvez également filtrer la réponse sur certains champs [6]: dans notre cas, il s’agit du nom, de la superficie, de la population et des démonymes.
Le résultat est donné sous forme de fichier JSON lisible par l’homme :
[
{
"name": {
"common": "Honduras",
"official": "Republic of Honduras",
"nativeName": {
"spa": {
"official": "Rep\u00fablica de Honduras",
"common": "Honduras"
}
}
},
"demonyms": {
"eng": {
"f": "Honduran",
"m": "Honduran"
},
"fra": {
"f": "Hondurienne",
"m": "Hondurien"
}
},
"area": 112492.0,
"population": 9892632
},
{
"name": {
"common": "Costa Rica",
"official": "Republic of Costa Rica",
"nativeName": {
"spa": {
"official": "Rep\u00fablica de Costa Rica",
"common": "Costa Rica"
}
}
},
"demonyms": {
"eng": {
"f": "Costa Rican",
"m": "Costa Rican"
},
"fra": {
"f": "Costaricaine",
"m": "Costaricain"
}
},
"area": 51100.0,
"population": 5309625
},
{
"name": {
"common": "Guatemala",
"official": "Republic of Guatemala",
"nativeName": {
"spa": {
"official": "Rep\u00fablica de Guatemala",
"common": "Guatemala"
}
}
},
"demonyms": {
"eng": {
"f": "Guatemalan",
"m": "Guatemalan"
},
"fra": {
"f": "Guat\u00e9malt\u00e8que",
"m": "Guat\u00e9malt\u00e8que"
}
},
"area": 108889.0,
"population": 18079810
},
{
"name": {
"common": "Panama",
"official": "Republic of Panama",
"nativeName": {
"spa": {
"official": "Rep\u00fablica de Panam\u00e1",
"common": "Panam\u00e1"
}
}
},
"demonyms": {
"eng": {
"f": "Panamanian",
"m": "Panamanian"
},
"fra": {
"f": "Panam\u00e9enne",
"m": "Panam\u00e9en"
}
},
"area": 75417.0,
"population": 4064780
},
{
"name": {
"common": "Nicaragua",
"official": "Republic of Nicaragua",
"nativeName": {
"spa": {
"official": "Rep\u00fablica de Nicaragua",
"common": "Nicaragua"
}
}
},
"demonyms": {
"eng": {
"f": "Nicaraguan",
"m": "Nicaraguan"
},
"fra": {
"f": "Nicaraguayenne",
"m": "Nicaraguayen"
}
},
"area": 130373.0,
"population": 6803886
},
{
"name": {
"common": "Belize",
"official": "Belize",
"nativeName": {
"bjz": {
"official": "Belize",
"common": "Belize"
},
"eng": {
"official": "Belize",
"common": "Belize"
},
"spa": {
"official": "Belice",
"common": "Belice"
}
}
},
"demonyms": {
"eng": {
"f": "Belizean",
"m": "Belizean"
},
"fra": {
"f": "B\u00e9lizienne",
"m": "B\u00e9lizien"
}
},
"area": 22966.0,
"population": 417634
},
{
"name": {
"common": "El Salvador",
"official": "Republic of El Salvador",
"nativeName": {
"spa": {
"official": "Rep\u00fablica de El Salvador",
"common": "El Salvador"
}
}
},
"demonyms": {
"eng": {
"f": "Salvadoran",
"m": "Salvadoran"
},
"fra": {
"f": "Salvadorienne",
"m": "Salvadorien"
}
},
"area": 21041.0,
"population": 6029976
}
]Cas 6.2 : Faire une requête à JokeAPI en utilisant Bruno
JokeAPI est une API REST gratuite et open source qui propose des blagues dans différents formats, par exemple JSON, XML, YAML ou texte brut [3].
- Ouvrez Bruno et sélectionnez Collections → + Créer une collection.
- Sélectionnez un nom pour votre collection, par exemple Exemple d’API.
- La collection créée est affichée dans le panneau de gauche. Pour créer une demande, cliquez sur … → Nouvelle demande.
- Sélectionnez le type de demande (HTTP) et précisez son nom par exemple blague_request.
- Dans le URL cellule, sélectionnez la méthode (OBTENIR) et entrez le point de terminaison https://v2.jokeapi.dev/joke/Any?blacklistFlags=religious,politique,raciste,sexiste&type=single.
L’URL a été construite en fonction des préférences que vous avez sélectionnées sur le site Web JokeAPI. Dans notre exemple, nous avons choisi n’importe quelle catégorie de blague, à l’exception des blagues nsfw, religieuses, politiques, racistes et sexistes (elles ont été signalées et mises sur liste noire). - Les paramètres que nous avons sélectionnés sur le site et copiés sont apparus dans la demande après le
?en tant que chaîne de requête vers l’URL du point de terminaison dans leGETchamp, séparé par&les uns des autres. Ils apparaîtront également dans un tableau dans le Paramètres languette. - Cliquez Envoyerattendez un peu… et vous recevrez en réponse une plaisanterie pas si mauvaise (« La génération de nombres aléatoires est trop importante pour être laissée au hasard. »). Faites attention au statut de la demande – c’est 200 OK, ce qui signifie le succès.
Il est important de noter que dans cet exemple, nous n’avons pas besoin de clé API pour accéder à notre ressource API REST. Sinon, nous devrions le transmettre comme en-tête dans un fichier séparé En-têtes languette.
Cas 6.3 : Faire une demande aux API ouvertes de la NASA avec la clé API
Le APOD (Astronomy Picture of the Day) de la NASA est un service populaire qui permet aux utilisateurs d’accéder à la photo ou à la vidéo quotidienne liée à l’astronomie, accompagnée d’une description. [7].
Faisons brièvement un exemple de documentation de l’API NASA APOD basé sur les conseils du 5ème paragraphe.
Documentation de l’API APOD de la NASA
Description: Cette API permet aux utilisateurs de récupérer des images ou des vidéos pour des dates, des plages spécifiques ou simplement celles sélectionnées au hasard sur le site Web APOD NASA.
Syntaxe de la requête: GET https://api.nasa.gov/planetary/apod
Méthodes d’authentification: Pour accéder à l’API APOD, vous devez inclure une clé API dans votre demande. Pour obtenir une clé API gratuite, vous devez soupirer sur https://api.nasa.gov/. Cette clé doit être incluse en tant que paramètre de requête dans la requête.
Paramètres et types de données: voir le tableau ci-dessous
| Paramètre | Taper | Description |
| clé_api* | chaîne | Votre clé API personnelle de la NASA. Si non spécifié, on peut utiliser DEMO_KEY pour vérifier à quoi ressemblent les demandes |
| date | chaîne (dateheure) | La date de l’image APOD à récupérer. Si non spécifié, la valeur par défaut est aujourd’hui |
| date de début | chaîne (dateheure) | Le début de la plage de dates pour la récupération des images. Ne peut pas être utilisé en une seule requête avec date |
| date_de fin | chaîne (dateheure) | La fin de la plage de dates pour la récupération des images. Utiliser avec start_date dans la même demande |
| compter | entier | Renvoie un nombre particulier d’images choisies au hasard. Ne pas utiliser avec les paramètres datetime |
| pouces | booléen | Renvoie l’URL de la miniature de la vidéo, si true. Dans le cas où l’objet APOD n’est pas une vidéo, ce paramètre est ignoré |
* — paramètres requis
Exemples de demande
Demande correcte avec le statut 200 OK
GET https://api.nasa.gov/planetary/apod?api_key=<your_API_key>
{
"copyright": "Simone Curzi",
"date": "2026-05-18",
"explanation": "Spiral galaxy NGC 3169 looks to be unraveling like a ball of cosmic yarn. It lies some 70 million light-years away, south of bright star Regulus toward the faint constellation Sextans. Wound up spiral arms are pulled out into sweeping tidal tails as NGC 3169 (left) and neighboring NGC 3166 interact gravitationally. Eventually the galaxies will merge into one, a common fate even for bright galaxies in the local universe. Drawn out stellar arcs and plumes are clear indications of the ongoing gravitational interactions across the deep and colorful galaxy group photo. The telescopic frame spans about 20 arc minutes or about 400,000 light-years at the group's estimated distance, and includes smaller, bluish NGC 3165 to the right. NGC 3169 is also known to shine across the spectrum from radio to X-rays, harboring an active galactic nucleus that is the site of a supermassive black hole.",
"hdurl": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165.jpg",
"media_type": "image",
"service_version": "v1",
"title": "Unraveling NGC 3169",
"url": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165px1024.jpg"
}Demande correcte avec le statut 200 OK pour une plage de dates
GET https://api.nasa.gov/planetary/apod?start_date=2025-03-03&end_date=2025-03-05&api_key=<your_API_key>
[
{
"date": "2025-03-03",
"explanation": "There's a new lander on the Moon. Yesterday Firefly Aerospace's Blue Ghost executed the first-ever successful commercial lunar landing. During its planned 60-day mission, Blue Ghost will deploy several NASA-commissioned scientific instruments, including PlanetVac which captures lunar dust after creating a small whirlwind of gas. Blue Ghost will also host the telescope LEXI that captures X-ray images of the Earth's magnetosphere. LEXI data should enable a better understanding of how Earth's magnetic field protects the Earth from the Sun's wind and flares. Pictured, the shadow of the Blue Ghost lander is visible on the cratered lunar surface, while the glowing orb of the planet Earth hovers just over the horizon. Goals for future robotic Blue Ghost landers include supporting lunar astronauts in NASA's Artemis program, with Artemis III currently scheduled to land humans back on the Moon in 2027.",
"hdurl": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_4096.jpg",
"media_type": "image",
"service_version": "v1",
"title": "Blue Ghost on the Moon",
"url": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_960.jpg"
},
{
"copyright": "Valerio Minato",
"date": "2025-03-04",
"explanation": "Why does this Moon look so unusual? A key reason is its vivid red color. The color is caused by the deflection of blue light by Earth's atmosphere -- the same reason that the daytime sky appears blue. The Moon also appears unusually distorted. Its strange structuring is an optical effect arising from layers in the Earth's atmosphere that refract light differently due to sudden differences in temperature or pressure. A third reason the Moon looks so unusual is that there is, by chance, an airplane flying in front. The featured picturesque gibbous Moon was captured about two weeks ago above Turin, Italy. Our familiar hovering sky orb was part of an unusual quadruple alignment that included two historic ground structures: the Sacra di San Michele on the near hill and Basilica of Superga just beyond. Your Sky Surprise: What picture did APOD feature on your friend's birthday? (post 1995)",
"hdurl": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg",
"media_type": "image",
"service_version": "v1",
"title": "A Quadruple Alignment over Italy",
"url": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg"
},
{
"copyright": "Todd Anderson",
"date": "2025-03-05",
"explanation": "On the right, dressed in blue, is the Pleiades. Also known as the Seven Sisters and M45, the Pleiades is one of the brightest and most easily visible open clusters on the sky. The Pleiades contains over 3,000 stars, is about 400 light years away, and only 13 light years across. Surrounding the stars is a spectacular blue reflection nebula made of fine dust. A common legend is that one of the brighter stars faded since the cluster was named. On the left, shining in red, is the California Nebula. Named for its shape, the California Nebula is much dimmer and hence harder to see than the Pleiades. Also known as NGC 1499, this mass of red glowing hydrogen gas is about 1,500 light years away. Although about 25 full moons could fit between them, the featured wide angle, deep field image composite has captured them both. A careful inspection of the deep image will also reveal the star forming region IC 348 and the molecular cloud LBN 777 (the Baby Eagle Nebula). Jump Around the Universe: Random APOD Generator",
"hdurl": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_9953.jpg",
"media_type": "image",
"service_version": "v1",
"title": "Seven Sisters versus California",
"url": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_960.jpg"
}
]Demande d’erreur avec le statut 400 Bad Request
GET https://api.nasa.gov/planetary/apod?date=2023-03-01&end_date=2023-03-01&api_key=<your_API_key>
{
"code": 400,
"msg": "Bad Request: invalid field combination passed. Allowed request fields for apod method are 'concept_tags', 'date', 'hd', 'count', 'start_date', 'end_date', 'thumbs'",
"service_version": "v1"
}7. Conclusion
Savoir lire (et peut-être écrire) la documentation de l’API n’est pas seulement une tâche technique ; il s’agit d’un élément essentiel d’une pratique réussie d’analyse de données, améliorant la collaboration, la reproductibilité, l’adoption et l’évolutivité. En donnant la priorité à une documentation claire et détaillée, les data scientists peuvent s’assurer qu’ils seront à l’aise avec les outils modernes.
Par exemple, de nombreux data scientists utilisent désormais des outils comme Claude Code, un agent d’IA de codage. Avec Claude Code, vos fichiers sont stockés localement sur votre ordinateur, et l’assistant IA les lit à partir de là et envoie le contenu texte à l’API Anthropic pour traitement. Il convient de noter qu’une documentation complète de l’API Claude décrit toutes les nuances de son fonctionnement. Plus précisément, l’API Claude est une API RESTful à https://api.anthropic.com qui fournit un accès programmatique aux modèles Claude et aux agents Claude gérés [8]. J’espère qu’après avoir lu cet article, vous comprendrez un peu mieux cette documentation (et d’autres) 🙂
Merci d’avoir lu!
Liste de références
- La page Web de l’API Cat : https://thecatapi.com/
- Documentation de Bruno :
- Page Web de JokeAPI : https://jokeapi.dev/
- Pays REST v3.1 : https://restcountries.com/
- Méthodologie de la DSNU : Indicatifs de pays ou de zones standard à usage statistique (M49)
- Liste des champs sur la page GitLab du projet : https://gitlab.com/restcountries/restcountries/-/blob/master/FIELDS.md
- API ouvertes de la NASA : https://api.nasa.gov/
- Claude API Docs – Un aperçu : https://platform.claude.com/docs/en/api/overview
You may also like
Comment décoder le paramètre de température dans les LLM
