Happy APIs : Débridons les APIS pour développer les humanités numériques
english below…
Ce billet pourra sembler rageur à certains, le fruit d’un énervement outrepassé ou encore d’une incompétence notoire à d’autres. Nous aimerions surtout qu’il soit l’occasion de faire avancer les pratiques des humanités numériques et d’en finir avec une certaine hypocrisie sur la soi-disant accessibilité des données via les APIs. Entendons-nous bien : nous ne sommes pas contre les APIs. Certaines requêtes complexes ne peuvent être effectuées que par ce biais et de ce point de vue elles sont indispensables. Nous sommes contre le fait qu’il s’agisse de la seule solution proposée aujourd’hui, une solution qui bride l’enseignement et la recherche en humanités numériques.
Reprenons. Il était une fois une fois une enseignante qui souhaitait initier ses étudiants en master art à la Digital Art History par la pratique. Et qui pour ce faire a recherché des corpus disponibles au format CSV maniables par des étudiants (c’est-à-dire pas avec des dizaines de milliers d’objets et 30 variables mais pas non plus une vingtaine d’objets et 3 variables ; l’idéal : entre 500 et 2000 objets avec 7 à 15 variables selon les exercices envisagés). Naïvement, elle pensait que cela lui prendrait 2 heures d’une recherche efficace sur le net. Une semaine plus tard, elle y était toujours et le constat était le suivant : seules quelques fichiers en lignes, en général fournis sur GitHub par des institutions américaines (le MoMA, le MET, le Carnegie Museum). Invariablement, et en particulier sur les sites européens, on la renvoyait vers l’utilisation de l’API qui permettait d’exploiter la base de données en ligne.
Autrement dit, lorsque l’on effectue une recherche sur une base de données (et il existe un nombre infini et passionnant de telles bases dans le domaine de la culture), aucun moyen de sauvegarder les résultats de la recherche sous format csv si ce n’est en passant par une API. Et c’est là qu’un immense découragement étreint le chercheur en quête d’une solution accessible et rapide pour initier ses étudiants aux joies des humanités numériques, ou même tout simplement pour faire un premier test sur un corpus qui pourrait devenir un sujet de recherche. Et ce y compris lorsque le chercheur en question ne renâcle pas à envoyer des lignes de commande dans son terminal, à adapter un code ou à déchiffrer un tutoriel entre 22h et 1h du matin.
Car que suppose l’API ? D’abord trouver sa page (et ce n’est pas toujours si facile), pourvu qu’elle existe. Puis demander une clé (que l’on est loin de vous donner de manière automatique – certaines n’arrivent jamais, ou des mois plus tard). Et surtout se plonger dans la documentation, plus ou moins (plus que moins) écrite par des informaticiens pour des informaticiens (des vrais, pas des chercheurs qui se piquent d’adapter du code et de changer la couleur de fond de leur terminal). Résultat : une suite de commandes et d’étapes, une version de python spécifique à télécharger, un export en Json (et non en csv), etc. Si encore toutes les API avaient un modèle identique, offraient la garantie de fonctionner et avaient une documentation minutieuse, le chercheur pourrait éventuellement accepter d’y consacrer au bas mot une journée. Mais non : toutes les API sont différentes, sont en général capricieuses et peu, mal documentées ou de manière incompréhensible pour le profane.
Quelles sont les conséquences de ces pratiques ?
Pour la pédagogie, c’est très simple : les enseignants-chercheurs n’ont pas le temps de se risquer à de tels méandres et se rabattent donc sur les mêmes jeux de données déjà cités, qu’ils saucissonnent et adaptent à la “va-comme-j’te-pousse” pour pouvoir répondre à des usages pédagogiques. On maintient la césure entre éducation technologique et éducation littéraire dénoncée par Simondon.
Pour la recherche, les étudiants en master, voire en doctorat, s’ils respectent les délais pour obtenir leur diplôme, ne peuvent se consacrer à la création de corpus. Restant dans une posture de commentaire Ils doivent donc s’appuyer sur des corpus existants. Or ces corpus ne sont pas accessibles. De même, de par l’injonction à la publication rapide et efficace, le chercheur se tournera plus volontiers vers des corpus qu’il peut tester rapidement. Et aujourd’hui, ces corpus accessibles sont souvent des corpus anglo-saxons si bien que nous délaissons de facto les données de nos propres fonds patrimoniaux.
Pour le mouvement de l’open data et de l’open access, une hypocrisie qu’il faut dénoncer : les API sont systématiquement annoncées comme le moyen par lequel les données sont mises à disposition des chercheurs. Or sous couvert de libération des données les APIs sont dans la pratique une restriction à leur accès.
Voilà pourquoi nous appelons à une prise de conscience. Pour nous, le scénario idéal serait celui-ci (et nous l’avons déjà rencontré : à l’impossible nul n’est tenu) : un bouton « exporter en CSV » présent sur chaque base de données. Lorsque que l’on clique dessus, on nous propose un menu nous demandant les variables à prendre en compte. Puis un second clic et la recherche effectuée dans la base de données est sauvegardée sous forme d’un fichier csv. Soit 2 clics pour vraiment libérer les données, favoriser l’enseignement et la recherche en humanités numériques.
Clarisse Bardiot, en collaboration avec Nicolas Thély
Happy API : Removing the limits from API to develop digital humanities
The tone of this post may seem to be overly aggravating to some, the fruit of an excessive outburst or the result of serious incompetency to others. We would especially like it to be an opportunity to advance digital humanities practices and end some hypocritical attitude toward the so-called accessibility of data via API. To be clear: we’re not against API. Some complex queries can only be made in this way and, from this point of view, they are thus essential. We are against the fact that this is the only solution proposed today, a solution that limits teaching and research in digital humanities.
To recap, once upon a time, there was a teacher who wanted to introduce her MA art students to Digital Art History through practice. And to do this, she looked for corpora available in CSV format that could be handled by students (i.e. not with tens of thousands of objects and 30 variables, but not with twenty or so objects and 3 variables either; ideally between 500 and 2000 objects with 7 to 15 variables depending on the exercises planned). Naively, she thought it would take her 2 hours to do an efficient search online. A week later, she was still looking. The conclusion was the following: only a few files were available online, usually provided on GitHub by American institutions (MoMA, MET, Carnegie Museum). Invariably, and in particular on European websites, she was referred to the use of an API in order to use the online database.
In other words, when searching for a database (and there is an infinite and exciting number of such databases in the field of culture), there is no way to save the search results in csv format except through an API. This is when frustration hits the researcher in search of an accessible and fast solution to initiate her students to the joys of digital humanities, or even simply to make a first test on a corpus which might become a research subject. And this even when the researcher in question does not hesitate to send command lines in her terminal, adapt a code or decipher a tutorial between 10pm and 1am.
What does using an API imply? First, to find its web page (and it’s not always that easy), provided it exists. Then to ask for a key (which is far from being given to you automatically – some never arrive, or months later). And above all, immerse yourself in the documentation, more or less (more than less) written by computer scientists for computer scientists (real ones, not researchers who need to adapt code and change the background color of their terminal). Result: a sequence of commands and steps, a specific python version to download, a Json export (and not a csv export), etc. If all the API still had an identical model, offered the guarantee of functioning and had meticulous documentation, the researcher could eventually agree to devote at least one day to it. But no: all APIs are different, are generally tricky to deal with, and with little and often poorly written documentation, or at least incomprehensible to the layman.
What are the consequences of these practices?
For pedagogy, it is very simple: teachers do not have the time to go through all these annoying steps and therefore fall back on the same data sets already cited, which they rearrange and adapt in a happy-go-lucky fashion to be able to respond to pedagogical needs. We maintain the gap between technological education and literary education that Simondon denounces.
For research, master’s students, or even doctoral students, simply cannot devote themselves to the creation of corpora if they want to adhere to the deadline for obtaining their degree. Remaining in a commentary position, they must therefore rely on existing corpus. However, these corpora are not accessible in an electronic format. Similarly, because of the pressure to publish often, researchers will be more willing to turn to corpora that he can test and use quickly. And today, these accessible corpora are often Anglo-Saxon corpora, so that we are de facto abandoning data from our own patrimonial funds.
A hypocritical situation must be denounced by people involved in the open data and open access movement: API are systematically announced as the means by which data are made available to researchers. However, under the guise of data release, API are in practice restricting access to data.
That is why we want to bring this issue to the foreground. For us, the ideal scenario would be this one (and we have already met it: to the impossible no one is bound): a button “export to CSV” present on each database. When we click on it, we are offered a menu asking us which variables to consider. Then a second click and the search in the database is saved as a csv file. That is 2 clicks to really free the data, promote teaching and research in digital humanities.
Clarisse Bardiot, in collaboration with Nicolas Thély
(Thanks to Michael E. Sinatra)
OpenEdition vous propose de citer ce billet de la manière suivante :
Clarisse Bardiot (7 septembre 2018). Happy APIs : Débridons les APIS pour développer les humanités numériques. DORRA-DH. Consulté le 28 mars 2025 à l’adresse https://doi.org/10.58079/nw3x
Bonjour,
Un organisme qui ne donne accès à ses données que par API est “louche”. En général on fait ça pour protéger sa base de données et contrôler les accès (ou on prévoit de le faire). Ou alors c’est peut-être de la fainéantise.
L’excuse de la “trop grande” taille de la base de données est rarement bonne.
A part pour les données dynamique, l’API devrait n’être qu’un bonus par rapport aux fichiers téléchargeables.
Intéressant point de vue. Pourquoi pas une charte des bonnes pratiques pour les API des institutions patrimoniales?
On pourrait y associer les SPARQL endpoints, à mon sens encore plus élitistes et lourds à utiliser, et pourtant présentés par beaucoup comme la panacée de la recherche ouverte.