Qu’est-ce qu’une API ?

[Préambule à l’usage de ceux qui seraient arrivés ici par hasard ou par Google : c’est un billet d’explications à l’usage des bibliothécaires par un bibliothécaire. Donc pas pour les développeurs, ni vraiment pour le grand public. Ceci étant posé, vous faites comme vous voulez ! ;-)]

Ce n’est que par une fréquentation suivie avec des API que j’ai fini par comprendre ce que c’est. Comme vous n’avez pas forcément les mêmes fréquentations que moi (que Dieu vous garde !), j’ai supposé qu’une petite explication pouvait être utile.

Ce billet est aussi un préliminaire au suivant (sur le Sudoc).

Un besoin vital pour une interrogation « en masse »

Imaginons que vous êtes un utilisateur normal, et que vous voulez savoir si Amazon, PriceMinister et la Fnac peuvent vous vendre 1 livre — à quel prix et dans quel état.

Vous allez sur chacun des trois sites, vous cherchez le livre, vous triez par prix ou par état, et vous comparez les trois sites et vous choisissez le fournisseur vous proposant le livre au meilleur état possible pour le meilleur prix possible. Vous y avez passé 15 minutes. Pour un livre.

Imaginons maintenant que vous avez besoin d’acheter 30 livres (par exemple parce que vous vous apprêtez à faire une thèse). Si vous êtes d’une patience ordinaire, vous comparerez pour deux ou trois livres, et vous choisirez un seul fournisseur pour l’ensemble de la commande.

Mais l’idéal serait de disposer d’un comparateur. Soit un quatrième site propose un tel service (il va interroger les 3 sites et vous remontera les réponses avec tris communs possibles), soit vous allez utiliser les API proposées par chacun de ces services.

A quoi ressemblent les données ?

Amazon, PriceMinister et la Fnac disposent de bases de données bibliographiques auxquelles vous n’avez pas accès directement : tout ce à quoi vous avez accès, c’est une interface web, c’est-à-dire un écran qui habille l’affichage des données et leur manipulation. L’interface sert d’intermédiaire entre vous et la base de données.

Que se passe-t-il sur cette interface ? On peut exprimer la même action de différentes manières :

1. Quand je lance une recherche « 9782910227739 » dans le champ de recherche d’Amazon, je génère une liste de résultats (avec un seul item) affichant le livre Quel modèle de bibliothèque ?. Cette liste de résultats a une URL : http://www.amazon.fr/s/ref=nb_ss_w?field-keywords=9782910227739
2. Donc si sur une page j’ai un lien hypertexte pointant vers cette page, et que je clique sur ce lien, c’est comme si je lançais une recherche dans la base. Donc cette URL est comme l’adresse web de la liste de résultats. [Il va de soi que cette page n’existe pas ailleurs que dans votre navigateur, le temps de l’affichage : elle n’est pas enregistrée sur les serveurs d’Amazon comme un document Word est stocké sur votre PC. Elle est créée à la volée].
3. Donc en saisissant cette URL dans la barre d’adresse de votre navigateur, vous demandez à Amazon de générer du code HTML, comportant tout un tas de balises et de texte, et la partie la plus intéressante contenant les références au livre cherché (le reste de la page étant à peu de choses près commun à toutes les pages de résultats)

   <div class="productData">

   <div class="productTitle">

   <a href="http://www.amazon.fr/Quel-mod%C3%A8le-biblioth%C3%A8que-Anne-Marie-Bertrand/dp/2910227731/ref=sr_1_1?ie=UTF8&amp;qid=1245781881&amp;sr=1-1">Quel modèle de bibliothèque ?</a>

   <span class="ptBrand">de Anne-Marie Bertrand</span>

   <span class="binding"> (<span class="format">Broché</span> - 19 décembre 2008)</span>

   </div>

   <div class="newPrice">

   <a href="http://www.amazon.fr/Quel-mod%C3%A8le-biblioth%C3%A8que-Anne-Marie-Bertrand/dp/2910227731/ref=sr_1_1?ie=UTF8&amp;qid=1245781881&amp;sr=1-1">Acheter neuf</a>: 

   <strike>EUR 34,00</strike> <span>EUR 32,30</span>

   </div>

   <div class="fastTrack">Pas de stock; commandez maintenant et nous vous livrerons cet article lorsqu'il sera disponible</div>

   <div class="sss">

   <span class="sssFree">Livraison gratuite</span>

   <span class="sssLastLine"> possible (voir fiche produit).</span>

   </div>

   </div>

   Le code ci-dessus produit ce résultat :
   

4. Bref, en utilisant l’URL http://www.amazon.fr/s/ref=nb_ss_w?field-keywords=9782910227739, vous générez le code ci-dessus.
5. Et si vous changez l’ISBN dans l’URL, vous obtenez des informations bibliographiques différentes, liées à l’ISBN recherchées.
6. Vous constatez donc que, quel que soit l’ISBN mis dans l’URL, le titre sera toujours au même endroit dans la page, dans la balise <a> elle-même incise dans la balise <div class= »productTitle »>, elle-même dans <div class= »productData »>.
7. Donc en fabriquant des URL, vous lancez une requête à Amazon qui vous renvoie du code correspondant à l’URL envoyée, avec des informations intéressantes dedans, toujours structurées de la même manière.
8. Pour manipuler les données « en masses », il serait préférable d’avoir des pages web ne comportant que les informations réellement intéressantes : après tout, le reste de la page ne vous intéresse pas !
9. Mais en fait, dans le scénario imaginé plus haut, pour chaque ISBN vous n’avez pas vraiment besoin du titre et de l’auteur, que vous connaissez — mais des prix et états d’exemplaires, informations qui ne sont pas dans cette page.

Bref :

1. vous voulez des données nettoyées de tout ce qui est couleur, taille de caractère, etc.
2. vous voulez tantôt des métadonnées bibliographiques classiques, tantôt d’autres types d’informations (prix, commentaires, pages de couvertures, etc.)

Finalement, utiliser des API c’est comme afficher une liste de résultats après requête, sauf que :

• la page obtenue est en XML au lieu d’être en HTML.
• il n’y a pas de formulaire de recherche : vous ne pouvez interroger la base que par des URL. Mais le résultat est comparable

Pour info : « API » veut dire « Application Programming Interface« . Vous voilà bien avancés !

Que veut dire « manipuler des données en masse » ?

Grosso modo, on peut trouver deux types d’utilisation de ces API :

1. Vous avez votre propre base bibliographique (au hasard : un catalogue de bibliothèque) et vous voulez y intégrer des contenus d’autres sources
2. Vous avez une liste de titres (sous forme de liste d’ISBN) et vous voulez extraire d’Amazon & consorts des informations sur la base.

1. Vous avez votre base bibliographique

Quand on interroge votre catalogue, le moteur utilise une feuille modèle ressemblant à ceci :

Titre : $title
Auteur : $author
Année : $annee
ISBN : $isbn

Où les mots précédés d’un $ sont des variables : selon les notices affichées, ce sera le titre, l’auteur et l’année de publication de tel ou tel document.

L’encodage sera évidemment plus complexe, et structuré en PHP, XSL ou autre. Mais cela n’a pas d’importance, on va faire comme si.

Donc dans la notice du document qui s’affiche, vous voulez qu’apparaisse la liste des autres éditions (si existantes) du même ouvrage. WorldCat propose une API intitulée getEditions : si vous structurez une URL sous la forme : http://xisbn.worldcat.org/webservices/xid/isbn/9782765406259?method=getEditions&format=xml&fl=form,year,lang,ed, WorldCat produit la liste des ISBN de toutes les éditions de l’ouvrage auquel appartient l’ISBN 9782765406259, sous la forme d’un fichier XML :

Si vous savez qu’on peut interroger votre catalogue avec une URL de requête sous la forme : http://catalogue.bibliotheque.fr/search?isbn=9782765406259, vous allez pouvoir bricoler le code suivant qui va générer des liens vers d’autres notices.

• Pour une notice en cours d’affichage dans votre Opac, dont l’ISBN est connu (variable $isbn), il va interroger WorldCat pour récupérer les ISBN des autres éditions
• Et il va générer une URL de requête dans votre catalogue contenant chacun de ces ISBN
• Ainsi pour chaque notice détaillée dans votre Opac, des liens vers les autres éditions du même ouvrage seront proposées

Précision : ce code n’existe pas, il ne correspond à rien. Je me suis inspiré de langages existants pour produire un truc à peu près compréhensible pour n’importe qui. Ce qui se trouve après les caractères # est du commentaire, non pris en compte par le programme

new variable FichierWorldcat = concat(« http://xisbn.worldcat.org/webservices/xid/isbn/ &raquo;, $isbn)
# à partir de l’ISBN en cours, il structure l’URL d’interrogation vers WorldCat

for each $FichierWorldcat.rsp.isbn
# pour chaque contenu de balise « isbn » trouvée dans le fichier XML de WorldCat, il crée un lien vers votre catalogue

{ print <a href= »http://catalogue.bibliotheque.fr/search?isbn=$FichierWorldcat.rsp.isbn« >Autre édition</a>;

};

Evidemment, il serait préférable qu’un lien n’apparaisse que si le document existe réellement. Donc il faudrait que votre propre catalogue propose des API, pour que l’affichage du lien soit conditionné à la vérification d’existence d’un fichier XML dont l’adresse web serait : http://catalogue.bibliotheque.fr/api/isbn/9782765406259, par exemple. Ce fichier renverrait un certain message (infos bibliographiques, par exemple) si le livre est présent, et un autre message (balise <unknown/> par exemple) s’il n’est pas trouvé.

Bref, sur cet exemple les données de WorldCat vous permettraient de FRBRiser votre opac.

Autres exemples (rapidement)

De la même manière, en indiquant à LibraryThing, Amazon ou WorldCat un ISBN, ces bases vous proposent les données qu’ils sont capables d’associer à cet ISBN :

• page de couverture
• commentaires, notations, tags
• prix (coût, mais aussi prix littéraires ou autres)
• etc.

Les improbables API du Sudoc

<update>Les API Sudoc n’ont plus rien d’improbable, finalement. Je suis trop pessimiste et trop mauvaise langue (et j’aime me tromper !)</update>

Vous avez remarqué la fin de l’URL de WorldCat ? http://xisbn.worldcat.org/webservices/xid/isbn/9782765406259?method=getEditions&format=xml&amp;fl=form,year,lang,ed. Le paramètre fl permet de préciser les informations à fournir comme attributs. Ici, le format, l’année de publication, la langue et le numéro d’édition.

Maintenant, imaginons que le Sudoc propose les données de son catalogue sous forme d’API.

Par exemple, si vous avez un ISBN (toujours 9782765406259), l’URL http://www.sudoc.abes.fr/api/isbn/9782765406259 génèrerait un fichier XML ressemblant à ceci :

A cela, rajoutez la possibilité d’avoir un paramètre permettant de préciser quelles informations vous voulez voir ou non figurer (le PPN, etc.) sous la forme : http://www.sudoc.abes.fr/api/isbn/9782765406259&attributs=ti,au,year,ppn,isbn,loc

Vous pourriez ainsi disposer facilement de la liste des bibliothèques proposant le même exemplaire. Mieux : vous pourriez proposer un lien vers les catalogues de ces bibliothèques (dont l’URL serait donnée dans le fichier XML produit). Mieux encore, vous pourriez, si votre bibliothèque et vos lecteurs sont à Paris, ne générer de lien que pour les bibliothèques de la région Ile-de-France.

Bref, vous pourriez faire l’économie du message standard : « Vous n’avez pas trouvé ? Allez voir dans le Sudoc ». En fait, les données elles-mêmes du Sudoc seraient visibles directement sur votre Opac.

Bon alors, ces API Sudoc, c’est pour quand ?… La réponse sera peut-être : attendez que le Sudoc soit dans WorldCat et utilisez alors les API WorldCat en filtrant sur les réponses émanant du Sudoc… Wait and see !

2. Vous avez une liste de titres (sous forme de liste d’ISBN) et vous voulez extraire d’Amazon & consorts des informations sur la base

[vous vous souvenez ? J’avais supposé deux scénarios possibles pour l’utilisation d’API, le premier étant la gestion d’un catalogue de bibliothèque en ligne et ses possibilités d’enrichissement]

L’utilisation d’API est intéressante aussi pour prospecter sur le contenu des bases bibliographiques disponibles sur le web. C’est ce qui m’a d’ailleurs amené à découvrir un peu les API WorldCat et LibraryThing.

Par exemple vous envisagez d’enrichir votre Opac avec diverses données. Vous hésitez entre Google Book Search, Amazon, WorldCat ou LibraryThing. Et vous excluez de les utilisez tous les trois parce que, pour un lecteur, voir 2 nuages de tags et une liste de mots clés (plus l’indexation Rameau), c’est cruel !

La question ne se posera pas seulement quant à la nature des contenus que chaque fournisseur, mais aussi quand au taux de recouvrement de ces bases avec votre catalogue. Ainsi, LibraryThing a peut-être beaucoup plus d’ouvrages, mais surtout en anglais — ou autres considérations de ce genre. Par ailleurs, peut-être que, pour votre collection, WorldCat vous proposera plus de commentaires mais moins de couvertures, etc.

Donc vous pouvez définir quel genre de contenus vous voulez proposer à vos lecteurs ; puis voir, pour chacun de ces contenus, quel pourcentage de vos livres chaque base contient.

C’est ce que j’ai fait avec mon échantillon de 1000 ISBN : j’ai mis cette liste dans un fichier XML, et pour chaque ISBN, j’ai généré des requêtes en API.

Que sont les API Key ?

J’ai été bloqué chez Amazon et WorldCat : il faut être enregistré (mais c’est gratuit) pour pouvoir vraiment utilisé leurs API. Lors de l’enregistrement, ces sites me fournissent un identifiant (une série de chiffres, voire un truc alphanumérique).

Chaque fois que vous voulez lancer une requête par API (sous forme d’URL contenant un ISBN), il faut rajouter quelque chose comme : « &key=1234425767897 », afin qu’Amazon ou WorldCat sache que c’est vous et pas un autre qui a fait cette requête. Cela facilite leurs statistiques et — si nécessaire — leur facturation…

Bon, il y a un autre intérêt, qui l’est aussi pour nous : une API permet aussi de manipuler les données elles-mêmes pour les modifier. Par exemple si vous avez un blog sous WordPress, certains programmes vous permettent de modifier vos articles, d’en créer de nouveaux, de rajouter des tags, etc. sans passer par l’interface en ligne : cela signifie que WordPress expose vos données sous forme de fichiers XML. Il faut donc que l’accès à ces fichiers soit conditionné à la fourniture d’un identifiant, surtout si vous voulez modifier lesdites données. D’où l’utilité de la clé.

En outre (mais j’ai l’impression que ce n’est pas systématique), une clé peut être associée à un site web. C’est-à-dire que si vous voulez enrichir vos notices de commentaires issus d’Amazon, l’URL de votre catalogue doit être indiquée à Amazon pour que celui-ci vous renvoie les résultats XML demandés.

Si bien que pour tester le contenu des bases par propulsions de listes XML d’ISBN stockées dans des fichiers sur mon PC — impossible !

Conclusion

Un informaticien (ou quelqu’un de plus compétent que moi) trouvera(it) certainement beaucoup d’erreurs et d’approximations dans ce billet, qui ne ressort que de la pratique que j’ai eu de tous ces outils.

Je les invite à réagir (avec leur indulgence coutumière) en commentaire. De toute façon, mon objectif n’est pas que toutes les personnes ayant lu ce billet soient capables de manipuler des API, mais qu’elles soient capables de comprendre ce dont on parle quand le mot arrive dans la conversation.

Je signalerai enfin que les API sont une forme de web services (ou, si vous préférez : dans les web services, on trouve notamment les API). Comme c’est le cas le plus fréquent, les deux expressions en viennent à être interchangeables.

<update après ce commentaire>Les web services sont les développements fait sur un site pour exploiter les API d’un autre site.</update>

Mais je ne développerai pas davantage sur ce terrain. <update>Et je fais bien !</update>