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

Webservice Koha

By joncour_g

Webservice Koha

  • 28
Loading comments...