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.

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

Im Moment kann Koha nur als Datenprovider agieren. Es kann keine Daten von anderen Repositories harvesten. Eines der größten Hindernisse für den Ausbau von Koha als Serviceprovider ist die Tatsache, dass Koha nur MARC-Daten nativ indexieren kann.

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

In der Voreinstellung liefert Koha keine Exemplarinformationen über OAI-PMH aus, aber dies kann über die Option include_items in der Konfigurationsdatei, die im Systemparameter :ref:`OAI-PMH:ConfFile <oai-pmh-conffile-label> verlinkt wird, aktiviert werden.

Bitte beachten Sie, dass die unten gezeigte Beispielkonfigurationsdatei sowohl marc21 als auch marcxml enthält, da marc21 das laut OAI-PMH guidelines empfohlene Metadaten-Präfix ist, während marcxml vor Koha 23.11 das Einzige war (und der Support für marc21 seit Koha 17.05 verfügbar ist).

Beispiel für eine 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
  marc21:
     metadataPrefix: marc21
     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
  marcxml:
     metadataPrefix: marcxml
     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

Die Möglichkeiten sind:

xsl_Datei: Pfad zu einer XSLT-Datei, die für die Umwandlung der Koha MARCXML-Daten in die erforderliche Struktur/das erforderliche Format verwendet wird. Dies kann zum Beispiel nützlich sein, wenn Sie einige spezifische Dublin-Core-Felder statt der Standardfelder generieren möchten.
include_items: Wenn dieser Wert auf 1 gesetzt ist, werden Exemplarinformationen in die Antwort entsprechend des Mappings im MARC-Framework aufgenommen.
erweitert_avs: Wenn dieser Wert auf 1 gesetzt wird, werden alle codierten Werte mit Beschreibungen erweitert. Dazu gehören Bibliotheksnamen, Beschreibungen des Medientyps, Beschreibungen der Normdatenwerte und Beschreibungen der Klassifizierungsquelle.

Alle diese Optionen können mit verschiedenen metadataPrefix-Einträgen verwendet werden, so dass die Nutzer die eine oder die andere Option anfordern können.

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>

Suche

Diese URL: http://meinserver.org:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs besteht aus den folgenden Komponenten:

Basis-URL des SRU-Servers: http://meinserver.org:9999/biblios?
Suchanfrage mit den 3 benötigten Parametern: version, operation und query. Die Parameter innerhalb der Suche haben die Form Schlüssel=Wert und können mit dem &-Zeichen aneinander gereiht werden.

Es können weitere zusätzliche Parameter zur Suche hinzugefügt werden, z.B. maximumRecords zur Angabe der maximalen Anzahl an Datensätzen, die vom Server zurückgegeben werden sollen. Zum Beispiel wird http://meinserver.org:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs&maximumRecords=5 nur 5 Datensätze vom Server abrufen.

Der Parameter „operation“ kann zwei Werte haben: scan oder searchRetrieve.

Wenn operation=searchRetrieve ist, dann sollte der Parameter search eine Suchanfrage enthalten. Z.B. operation=searchRetrieve&query=reefs

Wenn operation=scan ist, dann sollte der Suchparameter scanClause sein. Z.B. operation=scan&scanClause=reefs

etc/zebradb/biblios/etc/bib1.att definiert die Indizes für Zebra/Z39.50 in Ihrem System. Zum Beispiel gibt es Indizes für Schlagworte und Titel: att 21 Subject und att 4 Title.

In der Datei pqf.properties, die im Verzeichnis etc/zebradb/pqf.properties liegt, können wir sehen, dass es einen Zugangspunkt gibt, der bereits den Subject-Index verwendet (index.dc.subject = 1=21), während ein anderer den Title-Index verwendet (index.dc.title = 1=4). Wir wissen, dass es unser Subject-Index ist, da wir zuvor in bib1.att gesehen haben, dass er mit =1=21 in Z39.50 aufgerufen wird. Also zeigt index.dc.subject= 1=21 auf unseren Subject-Index. Und Title wurde mit 1=4 aufgerufen, also ist index.dc.title = 1=4 korrekt für unseren Titel-Index. Wir können jetzt die Abfrage wie in einem Suchfeld konstruieren, indem wir den Parameter „query“ voranstellen: query=Subject=reefs and Title=coral sucht nach „reefs“ als Schlagwort und coral im Titel. Die vollständige URL wäre dann: http://meinserver.org:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral. Wenn man nun die Ergebnisse auf 5 Datensätze beschränken möchte, macht man dies so: http://meinserver.org:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral&maximumRecords=5

Wir können auch mit Trunkierung und Beziehungen arbeiten. Diese werden ebenfalls in der Datei pqf.properties definiert. So werden die Positionseigenschaften definiert als:

 position.first              = 3=1 6=1
# "first in field"
 position.any                = 3=3 6=1
   # "any position in field"

Als weiteres Beispiel: wenn „coral“ an Anfang des Titels stehen soll, kann man die folgende Abfrage verwenden: http://meinserver.org:9999/biblios?version=1.1&operation=searchRetrieve&query=Title=coral first

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 selbstdokumentierende ILS-DI-Schnittstelle die vollständigste Schnittstelle und ihre Dokumentation ist unter https://IHRKATALOG/cgi-bin/koha/ilsdi.pl verfügbar, sobald der Systemparameter :ref:`ILS-DI <webservices-ils-di-system-preferences-label>`aktiviert wurden.

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 im Benutzerkonto anlegen zu können, muss der Systemparemter RESTOAuth2ClientCredentials aktiviert sein.

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

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

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

Koha generiert ein Paar aus Client ID/Secret, das dazu verwendet werden kann, Koha mit anderen Anwendungen als authentifizierter Anwender zu verbinden
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.