Panorama des Webservices de Koha
Gwendal JONCOUR
Qu'est ce qu'un webservice ?
Un service web est un protocole d'interface informatique de la famille des technologies web permettant la communication et l'échange de données entre applications et systèmes hétérogènes dans des environnements distribués.
Wikipedia
A Web service is a software system designed to support interoperable machine-to-machine interaction over a network.
W3C
C'est à dire
- Interface machine - machine
- Indépendant du système ou langage utilisé
- Reposant sur les standards du Web
Serveur
Webservice
Script JS
Client lourd
Appli mobile
...
Pourquoi ce panorama ?
KOHA
Rest API
(BibLibre)
SRU
ILS-DI
SIP
SVC
Koha propose plusieurs Webservices
RSS
Chaque webservice a...
- Son implémentation
- Son utilité
- Ses avantages
- Ses défauts
- Ses limites
SRU
Search/Retrieve via URL
Généralités
- Service de recherche catalogue
- Interroge le serveur d'indexation
- Héritier du protocole Z39.50
- Utilise le langage de requête CQL
A quoi ça sert ?
- Rechercher des données bibliographique
Comment ça se goupille ?
- Déclaration d'un serveur d'écoute dans koha-conf.xml
- Paramétrage de l'index de recherche dans etc/zebradb/pqf.properties
- Recherche depuis l'adresse suivant :
http://opac.koha.me:<port>/biblios?version=1.2&operation=searchRetrieve&query=<requete>&startRecord=<debut>&maximumRecords=<fin>
Ses avantages
- Recherche plus rapide que Koha
- Récupère les valeurs brutes des valeurs autorisées
- Basé uniquement sur la configuration du moteur d'indexation
Ses défauts et limites
- Ne bénéficie pas de la surcouche spécifique Koha
- Pas de facettes
- Sa méthode de tri par pertinence varie de celle de l'Opac
Démonstration
ILS-DI
Integrated Library System Discovery Interface
Généralités
- Projet initié en 2007 par la Digital Library Federation
- Recommandation parue en 2008
- Permet l'interface d'un SIGB avec un outil de découverte
A quoi ça sert ?
- Interagir en direct avec les modules :
- Catalogue
- Adhérents
- Circulation
Comment ça se goupille ?
- Activation depuis les paramètres système de Koha
- Restriction d'accès via IP
- Utilisation depuis l'adresse suivante :
https://opac.koha.me/cgi-bin/koha/ilsdi.pl/<function>?<params>
- Documentation disponible à la racine :
https://opac.koha.me/cgi-bin/koha/ilsdi.pl
Ses avantages
- Récupération d'informations entrecoupées entre les modules
- Par exemple, des notices biblio avec données d'exemplaire et historique de prêt
- Permet d'effectuer des actions de circulation :
- Renouvellement de prêt
- Création/Annulation de réservation
Ses défauts et limites
- Ne gère pas de session ni de droit d'accès hors IP
- Nécessite donc un proxy gérant les session ou bloquant les actions critiques
Démonstration
RESTful
Version non-communautaire par BibLibre
Généralités
- Développement par BibLibre du module Opac pour Drupal avec comme objectif une interaction entre le CMS et divers SIGB
- Développement d'une API RESTful pour Koha afin de pouvoir l'interfacer avec le module Drupal
A quoi ça sert ?
- Permet de déporter l'OPAC sur une autre interface
- Permet d'utiliser le module Opac pour Drupal 7
Comment ça se goupille ?
- Téléchargement du développement spécifique de BibLibre : http://git.biblibre.com/biblibre/koha-restful
- Création des liens symboliques, copie de la conf, installation des modules perl complémentaires
(cf. README du dépot git) - Appel des fonction via une URL :
https://opac.koha.me/cgi-bin/koha/rest.pl/<function>
- Documentation disponible via la commande :
perldoc opac/rest.pl
Ses avantages
- Respecte les pratiques REST
- Permet d'interagir avec de nombreuses fonctionnalités de Koha :
- Création/Modification/Suppression d'adhérent
- Compte lecteur
- Réservations
- Suggestions
- ...
Ses défauts et limites
- Est voué à disparaitre car une API communautaire est en développement
Démonstration
/SVC
Généralités
- Développement initié par LibLime quand la société faisait encore partie de la communauté Koha
- Evolution au fil des versions de Koha par différents acteurs, notamment BibLibre et ByWater Solutions
A quoi ça sert ?
- Fourre-tout de fonctions accessible de l'extérieur...
- ...bien souvent implémentées pour un usage interne de Koha (appel Ajax)
Comment ça se goupille ?
- Appel via une requête :
https://opac.koha.me/cgi-bin/koha/svc/<fonction> - Un peu de doc se trouve là :
https://wiki.koha-community.org/wiki/Koha_/svc/_HTTP_API - Pour le reste, il faut se débrouiller, fouiller les tickets, les utilisations internes, décrypter le script, etc.
Ses avantages
- De nombreuses fonctionnalités
- Interaction avec divers éléments de Koha
Ses défauts et limites
- Peu d'harmonisation entre ses différentes fonctions
- Possibilités variantes d'une version à l'autre de Koha
- Fonctionnalités souvent implémentées au besoin
- Pas de documentation complète
| 3.0 | authentication | Vérifie les identifiants passés et si l'utilisateur a la permission « editcatalogue », fourni un cookie de connexion |
| 3 0 | bib | Affiche ou édite une notice bib |
| 3.0 | bib_profile | Affiche les champs obligatoire pour enregistrer une notice bib |
| 3.0 | new_bib | Ajoute une nouvelle notice bib |
| 3.2 | config/systempreferences | Modifie une préférence système |
| 3.8 | import_bib | Importe une notice bib et ses données d'exemplaires |
| 3.10 | report | Exécute un rapport public ressort son résultat en json |
| 3.12 | cover_image | Supprime la couverture d'une notice |
| 3.16 | checkin | Retourne d'un document |
| 3.16 | checkouts | Emprunte un document |
| 3.16 | holds | Liste les réservation d'un utilisateur |
| 3.16 | renew | Renouvèle un emprunt |
| 3.18 | members/add_to_list | Ajouter un utilisateur à une liste |
| 3.18 | members/search | Recherche un utilisateur |
| 3.18 | letters | Récupère un format de lettre |
| 3.20 | records/preview | ??? |
| 3.20 | virtualshelves/search | Recherche une liste de lecture |
| 3.20 | barcode | Génère une image PNG d'un code-barre |
| 3.22 | cataloguing/framework | Récupère une grille de catalogage |
| 3.22 | cataloguing/metasearch | Recherche une métadonnée |
| 3.22 | localization | Affiche/Modifie/Ajoute/Supprime une localisation |
| 16.05 | hold/resume | Réactive une réservation |
| 16.05 | hold/suspend | Suspend une réservation |
| 16.11 | article_request | Gère une demande d'article |
| 17.05 | club/template/delete | Supprime un modèle de club |
| 17.05 | club/cancel_enrollment | Annule une adhésion à un club |
| 17.05 | club/delete | Supprime un club |
| 17.05 | club/enroll | Enrôle un utilisateur à un club |
| 17.05 | convert_report | Convertit un rapport guidé en rapport SQL |
Démonstration
Koha Webservice
?
Une nouvelle API RESTful
Et communautaire cette fois-ci
Cette API devra
- suivre des préceptes préétablies
- respecter strictement l'architecture RESTful
- devra être versionnée dans ses url
Objectif final :
Déprécier et enfin supprimer /svc
Premier choix établis
- Utiliser le framework Mojolicious pour créer l'API
- Utiliser le framework Swagger pour autodocumenter l'API
Quels sont ces préceptes ?
-
Utiliser de façon appropriée les méthodes HTTP
- POST / GET / PUT / DELETE
-
Utiliser de façon appropriée les statuts HTTP
- 200 / 400 / 404 / 500 / ...
-
Utiliser de façon appropriée les requête HTTP
- L'URL devra spécifier la ressource concernée
-
Utiliser de façon appropriée les corps de requête HTTP
- Les corps de requête devra servir à transmettre des objets
-
Utiliser la négociation de contenu HTTP pour retourner le bon type de contenu
- XML pour l'héritage, JSON à minima et JSONP pour permettre un appel depuis un autre domaine.
- Utiliser un cadre de documentation et de test
Qu'en est-il aujourd'hui ?
- Mojolicious et Swagger2 sont présents dans les dépendance optionnelles de Koha depuis la 3.22
- 3.22 : Gestion de utilisateurs :
- Lister tous les lecteurs ou afficher les détails d'un lecteur
- 16.05 : Gestion des réservations :
- Lister les réservations d'un lecteur, ajouter, modifier ou supprimer une réservation
- 16.11 : Gestion des villes :
- Lister les villes, récupérer, ajouter, modifier ou supprimer une ville
Quels avantages ?
- Une structure commune et solide
- Une documentation à jour
- Une création facilitée
- Une intégration à la communautaire facilitée