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.

Koha attualmente può avere solo il ruolo di fornitori di dati (Data Provider). Non può raccogliere da altri repositori. Il problema principale per far sì che Koha raccolga metadati da altri fornitori di dati è costituito dal fatto che il MARC è l’unico format di metadati che Koha indicizza in modo nativo. Visitare http://www.oaforum.org/tutorial/english/page3.htm per studiare come funziona il protocollo OAI-PMH.

Per default, Koha non include informazioni di copia nei result set di OAI-PMH, ma si possono aggiungere usando l’opzione include_items nel file di configurazione indicato in OAI-PMH:ConfFile.

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

Per attivare l’OAI-PMH in Koha modifica la prefrerenza di sistema OAI-PMH. Una volta abilitato puoi andare al link http://TUOCATALOGO/cgi-bin/koha/oai.pl per testare il sistema.

Esempio di configurazione OAI

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

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

In questo momento, l’autodocumentata ILS-DI è la più completa interfaccia ed è stata attivata come descritto nella preferenza di sistema ILS-DI section la documentazione è disponibile a https://YOURKOHACATALOG/cgi-bin/koha/ilsdi.pl

JSON reports services

Koha ha un JSON reports service per i report salvati usando le funzionalità Guided Reports Wizard o Report from SQL.

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/

OAuth2 client credentials grant

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

Interfaccia per la gestione dall” API key per gli utenti

Per premettere la creazionei di API key da parte degli utenti, la preferenza di sistema RESTOAuth2ClientCredentials deve essere abilitata per far apparire l’interfaccia nel record dell’utente.

  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