Depuis sa création, l’Abes développe une gamme d’applications destinées à la production, au traitement et à l’administration des données par les réseaux documentaires de l’ESR. Dès 2010, dans le cadre d’une politique volontariste en faveur de l’ouverture et de l’interopérabilité des données, une nouvelle catégorie de services s’est déployée pour une plus large réutilisation des données par les systèmes d’information :  une gamme de web services a ainsi  été mise progressivement à la libre disposition des professionnels de la documentation et des développeurs afin de faciliter l’extraction et la réutilisation des données en provenance des différentes bases gérées par l’Abes : Sudoc, Calames, IdRef, BACON, Theses.fr, STAR, STEP…

Jusqu’à présent, les web services de l’Abes étaient accompagnés de documentation sous forme de pages HTML, comme par exemple : http://documentation.abes.fr/sudoc/manuels/administration/aidewebservices/index.html.

Cependant, avec une quarantaine de web services disponibles aujourd’hui,  il devenait important d’harmoniser leur présentation, d’optimiser leur exposition et d’affiner leur documentation. Pour ce faire, en conformité avec sa politique de développement,  l’Abes a décidé de décrire ses API avec le standard OpenAPI : https://github.com/abes-esr/abes-politique-developpement/blob/main/08-Documentation.md

A noter : Le vocabulaire et les socles informatiques ayant considérablement évolué depuis 2010, on regroupe désormais ces ensembles de web services sous l’appellation générique d’API – Interface de Programmation Applicative, solution informatique permettant à des applications de communiquer entre elles et de s’échanger mutuellement des données.

Les API de l’Abes en OpenAPI

En 2010, la startup Swagger initiait un projet, devenu populaire au fil des années, qui permettait aux développeurs de définir et documenter des API en y incluant le code source. En 2016, des géants du secteur (Google, Microsoft, etc.) rejoignent l’initiative pour la faire évoluer. La spécification Swagger, alors renommée Spécification  OpenAPI définit, pour les API les plus courantes (de type REST / HTTP), un standard utilisé par les humains comme par les machines.

Lors du développement d’une nouvelle application, il est assez simple de produire la documentation de son API en OpenAPI, à l’aide de librairies logicielles, telles que SpringDoc. En effet, il suffit d’inclure ce type de librairie dans les dépendances de la nouvelle application, et d’utiliser les annotations adéquates, pour que la documentation soit automatiquement générée. Ainsi, les nouveaux web services développés par l’Abes – et bientôt utilisés par l’outil de curation paprika.idref.fr, intègrent une documentation OpenAPI :

• https://github.com/abes-esr/qualinka-microservices
• https://qualinka.idref.fr/swagger-ui.html

En revanche,  cette transformation s’avère plus compliquée pour les API plus anciennes : celles-ci n’utilisant pas forcément de framework  (de type Spring), il n’y a pas de moyen automatique et simple pour produire la documentation OpenAPI. L’effort de rédaction étant plus conséquent, il a été décidé de documenter en priorité les web services les plus utilisés.  Cette démarche s’appuie sur l’éditeur d’OpenAPI, Stoplight, outil gratuit pour la conception de documentation OpenAPI « à la main », via des formulaires qui aident et contrôlent la saisie. Ces documentations sont ensuite versionnées sur un espace Github dédié : https://github.com/abes-esr/openapi

Publication des OpenAPI de l’Abes sur api.gouv.fr

Pour publier les OpenAPI, le choix du site api.gouv.fr  s’est naturellement imposé, le site référençant les API du service public (collectivités, ministères, entreprises…) pour construire des services informatiques pour tous. De plus, les fonctionnalités disponibles facilitent largement l’usage et l’accès aux web services concernés.

Lors du chargement des OpenAPI sur api.gouv.fr,  un formulaire interactif est généré. Celui-ci liste les web services composant l’API et fournit, lorsque c’est pertinent, les liens vers la documentation HTML. Il est facile de saisir rapidement la structure et le fonctionnement de chacune des API, chaque paramètre possédant également sa description et une valeur exemple. Lorsque c’est nécessaire, une expression régulière donne le format attendu. A l’aide de ce formulaire, il est même possible de tester directement un appel au web service.

Retrouver les API mises à disposition sur api.gouv.fr :

• https://api.gouv.fr/producteurs/abes
• https://api.gouv.fr/documentation/api-sudoc
• https://api.gouv.fr/documentation/api-idref

Épatant : ça nous bouge !

Tel est le titre de la première notice en provenance d’ISSN France importée directement dans le Sudoc (PPN 260627062 ; ISSN 2804-715X). En l’occurrence, il s’agit d’un site web, occasion de rappeler que les ressources continues ne se limitent pas aux publications en série et aux collections, mais incluent aussi les « ressources intégratrices », c’est-à-dire des ressources dont le contenu peut être augmenté ou modifié par des mises à jour.

Cette intégration directe constitue une évolution fondamentale, la première de cette importance depuis la mise en place du Catalogue collectif national des publications en série (CCN-PS), ancêtre du Sudoc en matière de signalement et de localisation des ressources continues dans les bibliothèques françaises.

KohaLa est une association professionnelle francophone qui a pour objet le développement, la documentation, la protection, la promotion, et la diffusion du logiciel libre de gestion de bibliothèque Koha. Elle regroupe des utilisateurs et des développeurs et organise plusieurs événements afin de favoriser les partages d’expérience et de participer à l’évolution de Koha.

Lors de l’assemblée générale 2020 de l’association, nos adhérents membres du réseau Sudoc ont émis le souhait de voir KohaLa collaborer avec l’Abes pour réfléchir aux évolutions possibles dans les échanges entre Koha et les outils de l’Abes. Nous avons donc contacté l’Abes pour faire part de notre souhait de travailler ensemble selon des modalités à définir.

Les webservices de l’Abes à la rescousse

Au printemps 2021, KohaLa s’est lancé dans l’organisation d’un hackaton dont l’une des thématiques était l’amélioration des échanges entre Koha et l’Abes. Des bibliothécaires (dont des correspondants Sudoc) et prestataires Koha ont participé ainsi que des collègues de l’Abes. Les discussions se sont orientées vers l’exploitation possible des webservices mis à disposition par l’Abes et sur la question de l’usage qui pourrait en être fait dans Koha. Un besoin partagé est apparu : avoir un contrôle qualité de son catalogue et par là même du catalogue Sudoc.