Web services
Koha provides a number of APIs allowing access to it’s data and functions.
OAI-PMH
Metadata Harvesting (OAI-PMH) için Açık Arşivler Girişimi-Protokolü için iki ‘katılımcı’ grup vardır: Veri Sağlayıcıları ve Servis Sağlayıcıları. Veri Sağlayıcıları (açık arşivler, yazılım havuzu) metadata için ücretsiz erişim sağlar ve çok gerekli olmasa da diğer kaynaklara ya da tam metinlere de ücretsiz erişim imkanı sunabilir. OAI-PHM Veri Sağlayıcılar için kolay uygulanabilir, düşük bariyerli çözüm sağlar. Servis Sağlayıcılar metadata harvest etmek ve depolamak için Veri Sağlayıcılarının OAI arayüzlerini kullanırlar. Bunun Veri Sağlayıcılarına hiç bir canlı arama isteği olmayacağı anlamına geldiğini, hatta, hizmetlerin OAI-PMH aracılığıyla harvest edilen verilere dayandığını unutmayın.
Koha at present can only act as a Data Provider. It can not harvest from other repositories. The biggest stumbling block to having Koha harvest from other repositories is that MARC is the only metadata format that Koha indexes natively.
By default Koha won’t include item information in OAI-PMH result sets, but they can be added by using the include_items option in the a configuration file linked from OAI-PMH:ConfFile.
Bu sayfada OAI-PMH hakkında daha fazla bilgi edinebilirsiniz: `http://www.openarchives.org/pmh/
To enable OAI-PMH in Koha edit the OAI-PMH preference. Once enabled you can visit http://YOURKOHACATALOG/cgi-bin/koha/oai.pl to see your file.
Sample OAI conf file
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, URL (SRU) protokolü üzerinden Arama/Getirme eylemini uygular. http://www.loc.gov/standards/sru/ adresinde protokolün kendisi hakkında daha fazla bilgi bulunabilir. Uygulanan sürüm 1.1 sürümüdür.
Açıkla
If you want to have information about the implementation of SRU on a given server, you should have access to the Explain file using a request to the server without any parameter. Like http://myserver.com:9999/biblios/. The response from the server is an XML file that should look like the following and will give you information about the default settings of the SRU server.
<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>
Ara
Bu url : http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs aşağıdaki unsurlardan oluşur:
SRU sunucusunun temel url’si: http://myserver.com:9999/biblios?
3 gerekli parametre ile arama bölümü : sürüm, işlem ve sorgulama. Arama bölümü içerisindeki parametreler anahtar=değer biçiminde olmalı ve & karakteri ile kombine edilebilir olmalıdır.
Bir sunucu tarafından döndürülecek kayıtların sayısını gösteren örneğin maximumRecords için, sorguya isteğe bağlı parametreler eklenebilir. Böylece http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs&maximumRecords=5, sunucudan yalnızca ilk 5 sonucu alacaktır.
“Operation” anahtarı iki değer alabilir: scan ya da searchRetrieve.
operation=searchRetrieve ise, arama anahtarı sorgu olmalıdır. Şu şekilde : operation=searchRetrieve&query=reefs
If operation=scan ise, arama anahtarı scanClause olmalıdır. Şu şekilde : operation=scan&scanClause=reefs
etc/zebradb/biblios/etc/bib1.att sisteminizde mevcut olan Zebra/3950 dizinlerini tanımlar. Örneğin Konu ve Başlık dizinleri olduğunu göreceksiniz: att 21 konu ve att 4 başlık anılan sıraya göre.
etc/zebradb/pqf.properties altında bulunan pqf.properties dosyasında bir erişim noktasının zaten Konu dizinimi (index.dc.title = 1=4) kullandığını ve diğer bir tanesinin Başlık dizinimi (index.dc.title = 1=4) kullanmakta olduğunu görüyorum. Bunun benim Konu dizinim olduğunu bilmekteyim çünkü daha önce bib1.att dosyamda bunun =1=21 in Z3950: ile çağrıldığını gördüm, bu nedenle index.dc.subject = 1=21 doğru şekilde benim Konu dizinimi işaret etmektedir. Şimdi sorgumu, sadece kendisinden önce “query” (sorgu) anahtarı ile bir arama kutusunda yapacağım gibi oluşturabilirim: query=Subject=reefs ve Title=coral, konu içinde “reefs” araması ve başlık içinde “coral” araması yapar. Tam url şu şekildedir http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral Eğer sonuçları sadece 5 kayıt ile sınrlandırmak istersem, şöyle yapabilirim http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral&maximumRecords=5
Aynı zamanda kesme, ilişkiler, vs. gibi ayarları da inceleyebilirim. Bunlar pqf.properties dosyamda tanımlıdır. Örneğin şu şekilde tanımlanmış konum özelliklerini görebilirim:
position.first = 3=1 6=1
# "first in field"
position.any = 3=3 6=1
# "any position in field"
Yani, örnek olarak “coral” kelimesinin başlığın başında olmasını istiyorsam, şu sorguyu yapabilirim: http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Title=coral first
Retrieve
http://univ_lyon3.biblibre.com:9999/biblios?version=1.1&operation=searchRetrieve&query=coral reefs&maximumRecords=1 için yaptığım arama sadece bir kayıt getirdi. Yanıt şu şekilde görünür:
<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://YOURKOHACATALOG/cgi-bin/koha/ilsdi.pl
JSON reports services
Koha implements a JSON reports service for every report saved using the Guided reports wizard or Report from SQL features.
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:
Public reports
OpacBaseURL/cgi-bin/koha/svc/report?id=REPORTID
Non-public reports
StaffBaseURL/cgi-bin/koha/svc/report?id=REPORTID
There are also some additional parameters available:
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 [https://auth0.com/docs/api-auth/grant/client-credentials].
API key management interface for patrons
In order for API keys to be create for patrons, the system preference RESTOAuth2ClientCredentials must be enabled for the option to appear in a patron record.
Navigate to a patron record and select More > Manage API keys
If no API keys exist for a patron there will be a message prompting to generate a client id/secret pair
Enter a description for the client id/secret pair and click Save
Koha will generate a client id/secret pair for use to connect to Koha from other third-party systems as an authenticated client
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¬ext=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.