Services Web

Koha provides a number of APIs allowing access to it’s data and functions.

OAI-PMH

Concernant le « Open Archives Initiative-Protocol for Metadata Harvesting » (OAI-PMH) il y a deux groupes de « participants »: les fournisseurs de données, et les fournisseurs de services. Les fournisseurs de données (archives ouvertes, entrepôts numériques) offrent un accès gratuit aux métadonnées, et peuvent parfois offrir un accès gratuit à des articles en plein texte ou à d’autres ressources. OAI-PMH offre une solution facile a intégrer avec peu de barrières pour les fournisseurs de données. Les fournisseurs de services utilisent les interfaces OAI des fournisseurs de données pour moissonner et stocker des métadonnées. Notez que ceci signifie qu’il n’y a pas de recherche dynamique dans auprès des fournisseurs de données; les services sont plutôt basés sur les données moissonnées via OAI-PMH.

Actuellement, Koha ne peut agir que comme fournisseur de données. Il ne peut pas moissonner d’autres entrpôts. Le principal obstacle que rencontre Koha pour moissonner d’autres entrepôts, c’est que le format MARC est le seul format nativement indexé par Koha. Visitez http://www.oaforum.org/tutorial/english/page3.htm pour voir des diagrammes sur le fonctionnement d’OAI-PMH.

Par défaut, Koha n’inclut pas de données de l’exemplaire dans les sets OAI-PMH, mais elles peuvent être ajoutées en utilisant l’option include_items dans le fichier de configuration paramétré dans OAI-PMH:ConfFile.

Apprenez-en davantage à propos du OAI-PMH à l’adresse suivante : http://www.openarchives.org/pmh/

Pour activer OAI-PMH dans Koha, modifiez la préférence système OAI-PMH. Une fois que vous l’avez activée, allez sur http://YOURKOHACATALOG/cgi-bin/koha/oai.pl pour voir votre fichier.

Échantillon de Fichier de Configuration OAI

format:
  vs:
    metadataPrefix: vs
    metadataNamespace: http://veryspecial.tamil.fr/vs/format-pivot/1.1/vs
    schema: http://veryspecial.tamil.fr/vs/format-pivot/1.1/vs.xsd
    xsl_file: /usr/local/koha/xslt/vs.xsl
  marcxml:
     metadataPrefix: marxml
     metadataNamespace: http://www.loc.gov/MARC21/slim http://www.loc.gov/standards/marcxml/schema/MARC21slim
     schema: http://www.loc.gov/MARC21/slim http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd
     include_items: 1
  oai_dc:
     metadataPrefix: oai_dc
     metadataNamespace: http://www.openarchives.org/OAI/2.0/oai_dc/
     schema: http://www.openarchives.org/OAI/2.0/oai_dc.xsd
     xsl_file: /usr/local/koha/koha-tmpl/intranet-tmpl/xslt/UNIMARCslim2OAIDC.xsl

Serveur SRU

Koha implémente le protocole de recherche et de récupération via URL (SRU). Vous pouvez trouver plus d’informations à propos du protocole sur http://www.loc.gov/standards/sru/. La version implémentée est la version 1.1.

Explications

Si vous souhaitez avoir plus d’informations à propos de l’implémentation du SRU sur un serveur spécifique, allez sur le fichier Explain en envoyant une requête au serveur sans aucun paramètre. Par exemple http://myserver.com:9999/biblios/. La réponse du serveur est un fichier XML qui devrait ressembler à ce qui suit, et vous donnera des informations concernant les paramètres par défaut du serveur SRU.

       <zs:explainResponse>
            <zs:version>1.1</zs:version>
            <zs:record>
                 <zs:recordSchema>http://explain.z3950.org/dtd/2.0/</zs:recordSchema>
                 <zs:recordPacking>xml</zs:recordPacking>
                 <zs:recordData>
                 <explain xml:base="zebradb/explain-biblios.xml">
                 <!--
                 try stylesheet url: http://./?stylesheet=docpath/sru2.xsl
                 -->
            <serverInfo protocol="SRW/SRU/Z39.50">
                 <host>biblibre</host>
                 <port>9999</port>
                 <database>biblios</database>
            </serverInfo>
            <databaseInfo>
                 <title lang="en" primary="true">Koha 3 Bibliographic SRU/SRW/Z39.50 server</title>
                 <description lang="en" primary="true">Koha 3 Bibliographic Server</description>
                 <links>
                      <sru>http://biblibre:9999</sru>
                 </links>
            </databaseInfo>
            <indexInfo>
                 <set name="cql" identifier="info:srw/cql-context-set/1/cql-v1.1">
                      <title>CQL Standard Set</title>
                 </set>
                 <index search="true" scan="true" sort="false">
                 <title lang="en">CQL Server Choice</title>
                 <map>
                      <name set="cql">serverChoice</name>
                 </map>
            <map>
               <attr type="1" set="bib1">text</attr>
               </map>
          </index>
      <index search="true" scan="true" sort="false">
         <title lang="en">CQL All</title>
             <map>
<name set="cql">all</name>
</map>
<map>
<attr type="1" set="bib1">text</attr>
</map>
</index>
<!-- Record ID index -->
<index search="true" scan="true" sort="false">
<title lang="en">Record ID</title>
<map>
<name set="rec">id</name>
</map>
<map>
<attr type="1" set="bib1">rec:id</attr>
<attr type="4" set="bib1">3</attr>
</map>
</index>

Récupérer

Ma recherche pour http://univ_lyon3.biblibre.com:9999/biblios?version=1.1&operation=searchRetrieve&query=coral reefs&maximumRecords=1 récupère seulement une notice. La réponse ressemble à ceci:

          <zs:searchRetrieveResponse>
<zs:version>1.1</zs:version>
<zs:numberOfRecords>1</zs:numberOfRecords>
<zs:records>
<zs:record>
<zs:recordPacking>xml</zs:recordPacking>
<zs:recordData>
<record xsi:schemaLocation="http://www.loc.gov/MARC21/slim http://www.loc.gov/ standards/marcxml/schema/MARC21slim.xsd">
<leader> cam a22 4500</leader>
<datafield tag="010" ind1=" " ind2=" ">
<subfield code="a">2-603-01193-6</subfield>
<subfield code="b">rel.</subfield>
<subfield code="d">159 F</subfield>
</datafield>
<datafield tag="020" ind1=" " ind2=" ">
<subfield code="a">FR</subfield>
<subfield code="b">00065351</subfield>
</datafield>
<datafield tag="101" ind1="1" ind2=" ">
<subfield code="c">ita</subfield>
</datafield>
<datafield tag="105" ind1=" " ind2=" ">
<subfield code="a">a z 00|y|</subfield>
</datafield>
<datafield tag="106" ind1=" " ind2=" ">
<subfield code="a">r</subfield>
</datafield>
<datafield tag="100" ind1=" " ind2=" ">
<subfield code="a">20091130 frey50 </subfield>
</datafield>
<datafield tag="200" ind1="1" ind2=" ">
<subfield code="a">Guide des récifs coralliens / A Guide to Coral Reefs</subfield>
<subfield code="b">Texte imprimé</subfield>
<subfield code="e">la faune sous-marine des coraux</subfield>
<subfield code="f">A. et A. Ferrari</subfield>
</datafield>
<datafield tag="210" ind1=" " ind2=" ">
<subfield code="a">Lausanne</subfield>
<subfield code="a">Paris</subfield>
<subfield code="c">Delachaux et Niestlé</subfield>
<subfield code="d">cop. 2000</subfield>
<subfield code="e">impr. en Espagne</subfield>
</datafield>
<datafield tag="215" ind1=" " ind2=" ">
<subfield code="a">287 p.</subfield>
<subfield code="c">ill. en coul., couv. ill. en coul.</subfield>
<subfield code="d">20 cm</subfield>
</datafield>
......
<idzebra>
<size>4725</size>
<localnumber>2</localnumber>
<filename>/tmp/nw10BJv9Pk/upd_biblio/exported_records</filename>
</idzebra>
</record>
</zs:recordData>
<zs:recordPosition>1</zs:recordPosition>
</zs:record>
</zs:records>
</zs:searchRetrieveResponse>

ILS-DI

As of writing, the self documenting ILS-DI is the most complete interface and after it has been enabled as described in the ILS-DI system preferences section the documentation should be available at https://YOURKOHACATALOG/cgi-bin/koha/ilsdi.pl

JSON Web Services

Koha crée un web service JSON pour chaque rapport sauvegardé en passant par l’Assistant de rapport ou par Créer à partir d’une requête SQL.

By default reports will be non-public and only accessible by authenticated users. If a report is explicitly set to public it will be accessible without authentication by anyone. This feature should only be used when the data can be shared safely not containing any patron information.

The reports can be accessed using the following URLs:

  • Rapports publics

    • OpacBaseURL/cgi-bin/koha/svc/report?id=REPORTID

  • Rapports privés

    • StaffBaseURL/cgi-bin/koha/svc/report?id=REPORTID

Il existe également des paramètres complémentaires :

  • Instead of accessing the report by REPORTID you can also use the report’s name:

    • …/cgi-bin/koha/svc/report?name=REPORTNAME

  • For easier development there is also an option to generate an annotated output of the data. It will generate an array of hashes that include the field names as keys.

    • …/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1

Versioned RESTful API Effort

There is an ongoing effort to converge the APIs above into a single versioned set of modern RESTful endpoints documented using the OpenAPI standard and available by default under https://YOURKOHACATALOG/api/v1/

OAuth2 client credentials grant

Koha supports the OAuth2 client credentials grant as a means to secure the API for using it from other systems to adhere to current industry standards. More information on the OAuth2 client credentials grant standard can be found here.

API key management interface for patrons

Afin que les clés API soient créées pour les adhérents, la préférence système RESTOAuth2ClientCredentials doit être activée pour que l’option apparaisse dans la notice d’un adhérent.

  1. Navigate to a patron record and select More > Manage API keys

image1336

  1. If no API keys exist for a patron there will be a message prompting to generate a client id/secret pair

image1337

  1. Enter a description for the client id/secret pair and click Save

image1338

  1. Koha will generate a client id/secret pair for use to connect to Koha from other third-party systems as an authenticated client

    image1339

  2. Clicking the Revoke button next to an API credential pair will render the specific credential pair inactive until reactivated

Barcode image generator

Koha provides a barcode image generator on both the staff interface and the public interface. Both require a user to be logged in to use the service, to prevent abuse by third parties.

For example::

/cgi-bin/koha/svc/barcode?barcode=123456789&type=UPCE

The URL above will generate a barcode image for the barcode « 123456789 », using the UPCE barcode format.

The available barcode types are: * Code39 * UPCE * UPCA * QRcode * NW7 * Matrix2of5 * ITF * Industrial2of5 * IATA2of5 * EAN8 * EAN13 * COOP2of5

If no type is specified, Code39 will be used.

By default, the barcode image will contain the text of the barcode as well. If this is not desired, the parameter « notext » may be passed to supress this behavior.

For example::

/cgi-bin/koha/svc/barcode?barcode=123456789&notext=1

will generate a barcode image 123456789 without the text « 123456789 » below it.

This service can be used to embed barcode images into slips and notices printed from the browser, and to embed a patron cardnumber into the OPAC, among other possibilities.