Webservices

Koha provides a number of APIs allowing access to its data and functions.

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.

Learn more about OAI-PMH at https://www.openarchives.org/pmh/

Koha can act as both Data Provider and Service Provider. This section documents its use as Data Provider. For information on using it as a Service Provider, see the OAI repositories section.

To enable OAI-PMH in Koha edit the OAI-PMH preference. Once enabled you can visit https://opac.example.org/cgi-bin/koha/oai.pl to see your file.

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 OAI-PMH:ConfFile verlinkt wird, aktiviert werden.

Note that the sample conf file below contains entries for both marc21 and marcxml. The metadata prefix marc21 is the one recommended by the OAI-PMH guidelines <https://www.openarchives.org/OAI/2.0/guidelines-marcxml.htm>. The prefix marcxml is supported, but it is only included for backwards compatibility with older systems. The metadata prefix oai_dc is mandated by the standard as a fallback.

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: https://www.loc.gov/MARC21/slim https://www.loc.gov/standards/marcxml/schema/MARC21slim
     schema: https://www.loc.gov/MARC21/slim https://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd
     include_items: 1
  marcxml:
     metadataPrefix: marcxml
     metadataNamespace: https://www.loc.gov/MARC21/slim https://www.loc.gov/standards/marcxml/schema/MARC21slim
     schema: https://www.loc.gov/MARC21/slim https://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd
     include_items: 1
  oai_dc:
     metadataPrefix: oai_dc
     metadataNamespace: https://www.openarchives.org/OAI/2.0/oai_dc/
     schema: https://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 Exemplartyps, 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 implements the Search/Retrieve via URL (SRU) protocol. More information about the protocol itself can be found at https://www.loc.gov/standards/sru/. The version implemented is version 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

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

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*innen 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:

Public reports: https://opac.example.org/cgi-bin/koha/svc/report?id=REPORTID
Non-public reports: https://staff-interface.example.org/cgi-bin/koha/svc/report?id=REPORTID

Es sind einige weitere Parameter verfügbar:

Instead of accessing the report by REPORTID you can also use the report’s name: https://opac.example.org/cgi-bin/koha/svc/report?name=REPORTNAME or https://staff-interface.example.org/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: https://opac.example.org/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1 or https://staff-interface.example.org/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1

Versionierte RESTful API

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://opac.example.org/api/v1/

Die vollständige Dokumentation für diese APIs für Ihre Koha-Version finden Sie unter api.koha-community.org.

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.

Verwaltung von API-Keys für Benutzer

Um API-Keys für Benutzer*innen 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 eine*n Benutzer*in 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 provides a barcode image generator on both the staff interface and the OPAC. Both require a user to be logged in to use the service, to prevent abuse by third parties.

For example:

https://opac.example.org/cgi-bin/koha/svc/barcode?barcode=123456789&type=UPCE

or

https://staff-interface.example.org/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.

For example:

https://opac.example.org/cgi-bin/koha/svc/barcode?barcode=123456789&notext=1

or

https://staff-interface.example.org/cgi-bin/koha/svc/barcode?barcode=123456789&notext=1

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

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