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

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

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

Si noti che il file conf di esempio qui sotto contiene sia marc21 che marcxml, perché marc21 è il prefisso dei metadati raccomandato dalle linee guida OAI-PMH mentre marcxml era l’unico nell’esempio prima di Koha 23.11 (e il supporto per marc21 è stato aggiunto in Koha 17.05).

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

Le opzioni sono:

  • xsl_file: Percorso di un file XSLT che sarà usato per trasformare i dati Koha MARCXML nella struttura/formato necessari. Può essere utile, ad esempio, se si desidera generare alcuni campi Dublin Core specifici invece di quelli predefiniti.

  • include_items: Se impostato a 1, le informazioni sulle copie saranno incluse nella risposta secondo la mappatura del framework MARC.

  • expanded_avs: Se impostato su 1, tutti i valori codificati saranno espansi con le descrizioni. Ciò include i nomi delle biblioteche, le descrizioni dei tipi di elementi, le descrizioni dei valori autorizzati e le descrizioni delle fonti di classificazione.

Tutte queste opzioni possono essere utilizzate con diverse voci di metadataPrefix, consentendo agli utenti di richiedere l’una o l’altra.

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 system preferences, 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/

La documentazione completa di queste API per la propria versione di Koha si trova su 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

Per permettere la creazione di API key da parte degli utenti, la preferenza di sistema RESTOAuth2ClientCredentials deve essere abilitata per far apparire l’opzione 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

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.

Di default l’immagine conterrà anche il valore testuale del barcode. Se si desidera toglierlo, basterà passare il parametro “notext” per sopprimere il valore testuale.

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.