Serviços web

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

OAI-PMH

Para o protocolo Open Archives Initiative-Protocol for Metadata Harvesting (OAI-PMH), existem dois grupos de “participantes”: Provedores de Dados e Provedores de Serviços. Os Provedores de Dados (arquivos abertos, repositórios) oferecem acesso gratuito a metadados e podem, mas não necessariamente, oferecer também acesso gratuito aos textos completos ou a outros recursos. O OAI-PMH oferece aos Provedores de Dados uma solução de implementação simples e baixa barreira de entrada. Já os Provedores de Serviços utilizam as interfaces OAI dos Provedores de Dados para coletar (harvest) e armazenar metadados. Vale observar que isso significa que não há buscas em tempo real diretamente nos Provedores de Dados; em vez disso, os serviços são construídos com base nos dados previamente coletados via OAI-PMH.

Aprenda mais sobre o OAI-PMH em https://www.openarchives.org/pmh/

O Koha pode atuar tanto como Provedor de Dados quanto Provedor de Serviços. Esta seção documenta o uso como Provedor de Dados. Para informação como Provedor de Serviço, veja a seção OAI repositories.

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.

Por padrão, o Koha não inclui informações de exemplares nos conjuntos de resultados do OAI-PMH, mas elas podem ser adicionadas usando a opção include_items no arquivo de configuração vinculado em OAI-PMH:ConfFile.

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.

Amostra de arquivo OAI conf

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

As opções são:

xsl_file: Caminho para um arquivo XSLT que será usado para transformar os dados Koha MARCXML na estrutura/formato necessária. Pode ser útil, por exemplo, se você precisar que alguns campos específicos do Dublin Core sejam gerados em vez de apenas os padrão.
include_items: Se definida como 1, as informações do item serão incluídas na resposta de acordo com o mapeamento da estrutura do MARC.
expanded_avs: Se definido como 1, todos os valores codificados serão expandidos com descrições. Isso inclui nomes de bibliotecas, descrições de tipo de item, descrições de valor autorizadas e descrições de fonte de classificação.

Todas essas opções podem ser usadas com diferentes entradas de metadataPrefix, permitindo que os consumidores solicitem uma ou outra.

Servidor SRU

O Koha implementa o protocolo Search/Retrieve via URL (SRU). Mais informações sobre o protocolo em si podem ser encontradas em https://www.loc.gov/standards/sru/. A versão implementada é a versão 1.1.

Explicação

Se você quiser obter informações sobre a implementação do SRU em um determinado servidor, deve ter acesso ao arquivo Explain fazendo uma requisição ao servidor sem nenhum parâmetro. Por exemplo, http://myserver.com:9999/biblios/. A resposta do servidor é um arquivo XML que deve se parecer com o exemplo a seguir e fornecerá informações sobre as configurações padrão do servidor SRU.

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

Pesquisar

Esta url: http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs é composta pelos seguintes elementos:

url base do servidor SRU: http://myserver.com:9999/biblios?
parte de busca com os 3 parâmetros obrigatórios: version, operation e query. Os parâmetros dentro da parte de busca devem ter a forma key=value e podem ser combinados com o caractere &.

Pode-se adicionar parâmetros opcionais à consulta, por exemplo maximumRecords, indicando o número máximo de registros a serem retornados pelo servidor. Assim, http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs&maximumRecords=5 obterá apenas os primeiros 5 resultados do servidor.

A chave “operation” pode assumir dois valores: scan ou searchRetrieve.

Se operation=searchRetrieve, então a chave de busca deve ser query. Como em: operation=searchRetrieve&query=reefs

Se operation=scan, então a chave de busca deve ser scanClause. Como em: operation=scan&scanClause=reefs

etc/zebradb/biblios/etc/bib1.att define os índices Zebra/3950 que existem no seu sistema. Por exemplo, você verá que temos índices para Subject e para Title: att 21 Subject e att 4 Title respectivamente.

No arquivo pqf.properties, localizado em etc/zebradb/pqf.properties, vejo que um ponto de acesso já usa meu índice Subject (index.dc.subject = 1=21), enquanto outro usa meu índice Title (index.dc.title = 1=4). Sei que este é meu índice Subject porque, como vi anteriormente no meu arquivo bib1.att, ele é chamado com =1=21 no Z3950: então index.dc.subject = 1=21 aponta corretamente para meu índice Subject. E Title era chamado com 1=4, então index.dc.title = 1=4 aponta corretamente para meu índice Title. Agora posso construir minha consulta exatamente como faria em uma caixa de busca, apenas precedendo-a com a chave “query”: query=Subject=reefs and Title=coral busca “reefs” no subject e “coral” no title. A url completa seria http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral Se eu quiser limitar o conjunto de resultados a apenas 5 registros, posso fazer http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral&maximumRecords=5

Também posso brincar com truncate, relations, etc. Estes também são definidos no meu arquivo pqf.properties. Posso ver, por exemplo, as propriedades de position definidas como:

 position.first              = 3=1 6=1
# "first in field"
 position.any                = 3=3 6=1
   # "any position in field"

Assim, como exemplo, se eu quiser que “coral” esteja no início do title, posso fazer esta consulta: http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Title=coral first

Recuperar

Minha busca por http://univ_lyon3.biblibre.com:9999/biblios?version=1.1&operation=searchRetrieve&query=coral reefs&maximumRecords=1 recupera apenas um registro. A resposta se parece com isto:

          <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

Serviços de relatórios JSON

O Koha implementa um serviço de relatórios JSON para cada relatório salvo usando as funcionalidades Guided reports wizard ou Report from SQL.

Por padrão, os relatórios não serão públicos e só estarão acessíveis a usuários autenticados. Se um relatório for explicitamente definido como público, ele ficará acessível sem autenticação para qualquer pessoa. Esse recurso deve ser usado apenas quando os dados puderem ser compartilhados com segurança, sem conter nenhuma informação de usuários.

Os relatórios podem ser acessados usando as seguintes URLs:

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

Há também alguns parâmetros adicionais disponíveis:

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

Esforço de API RESTful versionada

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/

Documentação completa dessas APIs para a sua versão do Koha pode ser encontrada em api.koha-community.org.

Concessão de credenciais de cliente OAuth2

O Koha oferece suporte à concessão de credenciais de cliente OAuth2 como meio de proteger a API para uso a partir de outros sistemas, em conformidade com os padrões atuais da indústria. Mais informações sobre o padrão de concessão de credenciais de cliente OAuth2 podem ser encontradas aqui.

Interface de gerenciamento de chaves de API para usuários

Para que chaves de API sejam criadas para usuários, a preferência do sistema RESTOAuth2ClientCredentials deve estar habilitada para que a opção apareça no registro de um usuário.

Entre no registo de um leitor e selecione Mais > Gerir chaves API

Se não existirem chaves API para o leitor aparecerá uma mensagem para gerar o par identificador/segredo do cliente

Insira a descrição para o par e clique em Guardar

O Koha vai gerar um par identificador/segredo para ser usado na conexão ao Koha a partir de outros sistemas como cliente autenticado
Ao clicar no botão Revogar junto ao par da credenciais da API tornará o par de credenciais específico inativo até que seja reativado

Gerador de imagem de código de barras

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.

Por exemplo:

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

O URL acima vai gerar uma imagem com o código de barras “123456789”, usando o formato de código de barras UPCE.

Os tipos de código de barras disponíveis são: * Code39 * UPCE * UPCA * QRcode * NW7 * Matrix2of5 * ITF * Industrial2of5 * IATA2of5 * EAN8 * EAN13 * COOP2of5

Se o tipo não estiver especificado, será usado o tipo Code39 por omissão.

Por omissão, a imagem com o código de barras vai conter o texto do código de barras. Caso não deseje o texto, o parâmetro “notext” deve ser usado para suprimir este comportamento.

Por exemplo:

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

vai gerar uma imagem com o código de barras 123456789 sem o texto “123456789”.

Este serviço pode ser usado para embeber códigos de barras nos recibos e avisos impressos a partir do navegador, e para embeber um número de cartão de leitor no OPAC, entre outras possibilidades.