Web Services

Koha stellt eine Reihe von APIs für den Zugang zu seinen Daten und Funktionen bereit.

OAI-PMH

Für das Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) gibt es zwei Gruppen von „Teilnehmern“: Datenprovider und Serviceprovider. Datenprovider (offene Archive und Repositorien) ermöglichen freien Zugang auf ihre Metadaten und können, aber müssen nicht, freien Zugriff auf Volltexte und andere Ressourcen bereitstellen. OAI-PMH ist eine einfach zu implementierende, niedrigschwellige Lösung für Datenprovider. Serviceprovider verwenden die OAI-Schnittstellen der Datenprovider um Metadaten zu harvesten und zu speichern. Bitte beachten Sie, dass dies bedeutet, dass es keine Live-Suchanfragen an die Datenprovider gibt, sondern viel mehr werden Dienste auf Basis der über OAI-PMH gesammelten Daten angeboten.

Im Moment kann Koha nur als Datenprovider agieren. Es Kann keine Daten von anderen Repositories harvesten. Eines der Hindernisse für den Ausbau von Koha als Serviceprovider ist die Tatsache, dass Koha nur MARC-Daten nativ indexieren kann. Unter http://www.oaforum.org/tutorial/english/page3.htm finden Sie Diagramme zur genauen Arbeitsweise von OAI-PMH.

In der Voreinstellung liefert Koha keine Exemplarinformationen über OAI-PMH auf, aber dies kann über die Option include_items in der Konfigurationsdatei, die im Systemparameter OAI-PMH:ConfFile verlinkt wird, aktiviert werden.

Erfahren Sie mehr über OAI-PMH unter: http://www.openarchives.org/pmh/

Über den Systemparameter OAI-PMH können Sie die Schnittstelle in Koha aktivieren. Sobald OAI-PMH aktiviert ist, können Sie die Daten unter http://OPACURL/cgi-bin/koha/oai.pl abrufen.

Beispiel einer OAI-Konfigurationsdatei

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

SRU-Server

Koha implementiert das Protokoll Search/Retrieve via URL (SRU). Weitere Informationen über das Protokoll selbst können unter http://www.loc.gov/standards/sru/ abgerufen werden. Die implementierte Version ist 1.1.

Explain

Wenn Sie Informationen zur Implementierung der SRU-Schnittstelle für einen bestimmten Server in Erfahrung bringen möchten, können Sie über eine Anfrage an den Server ohne Parameter Zugriff auf die Explain-Datei nehmen. Zum Beispiel: http://meinserver.org:9999/biblios/. Die Antwort des Servers ist eine XML-Datei, die wie die nachfolgende aussehen sollte und Informationen über die Konfiguration des SRU-Servers enthält.

       <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>

Retrieve

Die Suche nach http://univ_lyon3.biblibre.com:9999/biblios?version=1.1&operation=searchRetrieve&query=coral reefs&maximumRecords=1 liefert nur einen Datensatz. Die Antwort sieht so aus:

          <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

Im Moment ist die selbstdokumentierte ILS-DI-Schnittstelle am vollständigsten und ihre Dokumentation ist unter https://IHRKATALOG/cgi-bin/koha/ilsdi.pl sichtbar, sobald sie über den Systemparameter ref:webservices-ils-di-system-preferences-label aktiviert wurde.

JSON Reports Services

Koha stellt eine JSON-Schnittstelle für Reports zur Verfügung, die als Geführter Report oder SQL-Report erstellt wurden.

In der Voreinstellung sind die Reports nicht öffentlich und daher nur für authentifizierte Benutzer mit entsprechenden Berechtigungen zugänglich. Wenn ein Report auf öffentlich gesetzt wurde, ist er auch ohne Authentifizierung abrufbar. Diese Funktion sollte nur dann verwendet erden, wenn die Daten auf sichere Weise geteilt werden und keine personenbezogenen Daten enthalten.

Die Reports können über die folgenden URLs aufgerufen werden:

  • Öffentliche Reports

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

  • Interne Reports

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

Es sind einige weitere Parameter verfügbar:

  • Statt den Report über die REPORTID aufzurufen, kann auch der Reportname verwendet werden:

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

  • Um die Entwicklung zu vereinfachen, gibt es auch eine Option für eine annotierte Ausgabe der Daten. Damit wird ein Array von Hashes generiert, welcher die Namen der Felder als Schlüssel enthält.

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

Versionierte RESTful API

Es gibt ein laufendes Projekt die oben genannten APIs in einem einigen versionierten Set von modernen RESTful Endpoints, dokumentiert über den OpenAPI-Standard und verfügbar unter https://IHRKATALOG/api/v1 zusammenfließen zu lassen

OAuth2 Client Credentials Grant

Koha unterstützt den OAuth2 Client Credentials Grant als eine Maßnahme um das API abzusichern, wenn es von anderen Systemen aus verwendet wird, und den aktuellen Industriestandards zu genügen. Weitere Informationen zum OAuth2 Client Credentials Grant-Standard finden Sie unter https://auth0.com/docs/api-auth/grant/client-credentials.

Verwaltung von API-Keys für Benutzer

Um API-Keys für Benutzer anlegen zu können und damit die entsprechenden Optionen im Benutzerkonto angezeigt werden, muss der Systemparemter RESTOAuth2ClientCredentials aktiviert sein.

  1. Rufen Sie einen Benutzerdatensatz auf und wählen Sie Mehr > API-Keys verwalten

image1336

  1. Wenn für einen Benutzer noch kein API-Key angelegt wurde, wird ein entsprechender Hinweis angezeigt

image1337

  1. Geben Sie eine Beschreibung für das Paar aus Client ID/Secret an und klicken Sie auf Speichern

image1338

  1. Koha generiert ein Paar aus Client ID/Secret, dass dazu verwendet werden kann, Koha mit anderen Anwendungen als authentifizierter Anwender zu verbinden

    image1339

  2. Klicken Sie auf die Schaltfläche „Widerrufen“ neben einem API-Key-Paar, um dieses zu deaktivieren bis es reaktiviert wird

Barcodebild-Generator

Koha verfügt über einen Generator für Barcodebilder in der Dienstoberfläche und im OPAC. Beide erfordern, dass der Benutzer angemeldet ist, um diesen Service zu nutzen, um Missbrauch durch Dritte zu verhindern.

Zum Beispiel:

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

Die obenstehende URL generiert ein Barcodebild für den Barcode „123456789“ im UPCE-Barcodeformat.

Die verfügbaren Barcodeformate sind: * Code39 * UPCE * UPCA * QRcode * NW7 * Matrix2of5 * ITF * Industrial2of5 * IATA2of5 * EAN8 * EAN13 * COOP2of5

Wenn kein Typ angegeben wird, wird Code39 verwendet.

In der Voreinstellung enthält das Barcodebild auch den Barcode als Text. Wenn dies nicht gewünscht wird, kann der Parameter „notext“ verwendet werden, um dies zu unterdrücken.

Zum Beispiel:

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

generiert ein Barcodebild für 123456789 ohne den Text „123456789“ darunter.

Dieser Service kann verwendet werden um Barcodebilder in Quittungen und Benachrichtigungen, die über den Browser gedruckt werden, einzubetten oder um die Ausweisnummer im OPAC als Barcode anzuzeigen.