Web services

Koha fornisce un certo numero di API per accedere ai suoi dati e funzioni.

OAI-PMH

Per il Protocollo OAI-PMH (Open Archives Initiative-Protocol for Metadata Harvesting) ci sono due gruppi di “partecipanti”: fornitori di dati e fornitori di servizi. I fornitori di dati (archivi aperti, repositori) danno libero accesso ai metadati, e possono offrire a loro discrezione accesso libero al full-text o ad altre risorse. OAI-PMH offre una soluzione semplice ai fornitori di dati. I fornitori di servizi usano le interfacce OAI dei fornitori di dati per raccogliere e conservare metadati. Questo implica che non saranno effettuate ricerche dall’utenza verso i fornitori di dati; se mai, i servizi sono basati sui dati raccolti via OAI-PMH.

Approfondisci il protocollo OAI-PMH su http://www.openarchives.org/pmh/

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.

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.

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.

Note that the sample conf file below contains both marc21 and marcxml, because marc21 is the metadata prefix recommended by the OAI-PMH guidelines while marcxml was the only one in the sample before Koha 23.11 (and support for marc21 was added in Koha 17.05).

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

The options are:

  • xsl_file: Path to an XSLT file that will be used for transforming the Koha MARCXML data into the needed structure/format. It can be useful, for example, if you need some specific Dublin Core fields to be generated instead of just the default ones.

  • include_items: If set to 1, item information will be included in the response according to the MARC framework’s mapping.

  • expanded_avs: If set to 1, all coded values will the expanded with descriptions. This includes library names, item type descriptions, authorized value descriptions and classification source descriptions.

All these options can be used with different metadataPrefix entries, allowing the consumers to request one or the other.

Server SRU

Koha implementa il protocollo Search/Retrieve via URL (SRU). Altre informazioni sul protocollo SRU si trovano a http://www.loc.gov/standards/sru/. Koha implementa la versione 1.1 di SRU.

Explain

Se vuoi avere informazioni sulla specifica implementazione SRU di un dato server, puoi accedere al file Explain facendo una richiesta al server senza alcun parametro. Tipo http://myserver.com:9999/biblios/. Il responso del server è un file XML che sarà simile a quello qui seguente e ti fornirà le informazioni sulla configurazione di default dello specifico 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>

Retrieve

La ricerca http://univ_lyon3.biblibre.com:9999/biblios?version=1.1&amp;operation=searchRetrieve&amp;query=coral reefs&maximumRecords=1 restituisce un solo record. La risposta è del tipo:

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

Per default i reports non sono pubblici e sono accessibili solo ad utenti autenticati. Se un report è messo esplicitamente a pubblico, allora sarà accessibile senza autenticazione da chiunque. Questa feature deve essere usata solo per condividere dati che non contengono informazioni sugli utenti.

I report possono essere acceduti usando i seguenti URLs:

  • Report pubblici

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

  • Report privati

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

Sono disponibili anche alcuni parametri:

  • Puoi accedere ai report con il REPORTID o con il nome del report:

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

  • Per facilitare lo svilippo c’è anche l’opzione di generare un output annotato dei dati. Si genererà un array di hash che include i nomi dei campi come chiavi.

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

Versioned RESTful API effort

E” in corso uno sforzo di sviluppo per far convergere le APIs sopradette in un singolo set di moderni RESTful endpoints documentati usando lo standard OpenAPI e disponibili di deafult all’indirizzo https://YOURKOHACATALOG/api/v1/

Full documentation for these APIs for your version of Koha can be found at api.koha-community.org.

OAuth2 client credentials grant

Koha supporta il OAuth2 client credentials grant come metodo per mettere in sicurezza le API in maniera conforme ai correnti standard. Maggiori informazioni sullo standard OAuth2 client credentials grant sono disponibili qui.

Interfaccia per la gestione dall” API key per gli utenti

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.

  1. Vai a un record utente e scegli Più > Gestione API keys

image1336

  1. Se non c’è una API key per un utente, un messaggio avviserà di creare una coppia client id/secret.

image1337

  1. Indica una descrizione per la coppia client id/secret e salva

image1338

  1. Koha genererà una coppia client id/secret da usare per connessioni con autenticazione da sistemi di terze parti a Koha

    image1339

  2. Cliccando sul bottone Revoca posto accanto a una coppia di credenziali di un’API, disattiverà quella credenziale fino ad operazione contraria

Generatore barcode (immagine)

Koha fornisce un generatore di una immagine con codici a barre sia nell’intranet sia nell’Opac. In entrambi i casi l’utente deve essere loggato per usarlo, questo per prevenire abusi.

Per esempio:

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

L’URL qui sopra genererà un’immagine con codici barre usando il valore «123456789» e il formato di barcode UPCE.

I tipi di formato disponibli sono: * Code39 * UPCE * UPCA * QRcode * NW7 * Matrix2of5 * ITF * Industrial2of5 * IATA2of5 * EAN8 * EAN13 * COOP2of5

Se non viene specificato viene usato il tipo Code39.

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 suppress this behavior.

Per esempio:

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

genererà un’immagine con codice a barre il cui valore sarà 123456789 e non avrà il testo “123456789” sotto i codici a barre.

Questo servizio può essere usato per inglobare immagini di codici barre nelle ricevute e negli avvisi stampati del browser, oppure per inserire il barcode della tessera utente nell’Opac. Oppure per altri utilizzi.