Serviços Web

O Koha fornece um número de APIs permitindo o acesso aos seus dados e funções.

OAI-PMH

Para o Open Archives Initiative-Protocol for Metadata Harvesting (OAI-PMH) há dois grupos de “participantes”: Fornecedores de Dados e Fornecedores de Serviços. Os Fornecedores de Dados (arquivos abertos, repositórios) fornecem acesso livre ao metadados, e podem, mas não necessariamente, fornecer acesso livre aos textos completos e a outros recursos. O OAI-PMH fornece uma solução simples e sem entraves para os Fornecedores de Dados. Os Fornecedores de Serviços utilizam a interface OAI dos Provedores de dados para agregar e armazenar os dados/metadados. Note que isto que não existe uma pesquisa direta nos provedores de dados; os serviços baseam-se nos dados agregados pelo protocolo.

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

O Koha pode funcionar como fornecedor de dados e como fornecedor de serviços. Esta secção documenta o seu uso como fornecdor de dados. Para mais informações sobre o seu uso como fornecedor de serviços, verifique a secção repositórios OAI.

Para activar o OAI-PMH no Koha, edite a preferência OAI-PMH. Uma vez ativado, pode aceder a https://opac.example.org/cgi-bin/koha/oai.pl para visualizar o seu ficheiro.

Por omissão, o Koha não inclui as informações de exemplar nos resultados dos conjuntos OAI-PMH, mas podem ser adicionadas usando a opção include_items no ficheiro de configuração definido na preferência de sistema OAI-PMH:ConfFile.

Note que o ficheiro de configuração de exemplo abaixo contém entradas tanto para marc21, como para marcxml. O prefixo de metadados marc21 é o recomendado pelos guias do OAI-PMH <https://www.openarchives.org/OAI/2.0/guidelines-marcxml.htm>. O prefixo marcxml é suportado, mas foi incluído apenas para garantir a compatibilidade com sistemas mais antigos. O prefixo de metadados oai_dc é requerido pela norma como opção de contingência.

Exemplo de ficheiro de configuração 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: 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 ficheiro XSLT que será usado para transformar os dados em MARCXML para a estrutura/formato necessário. Pode ser útil, por exemplo, se necessitar de campos Dublin Core específicos em vez de usar os campos por omissão.
include_items: Se definido como 1, a informação dos exemplares será incluída na resposta de acordo com o mapeamento dos modelos MARC.
expanded_avs: Se definido como 1, todos os valores codificados serão expandidos com a descrição. Pode incluir os nomes das bibliotecas, as descrições dos tipos de documento, as designações dos valores autorizados ou as descrições das fontes de classificação.

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

Servidor SRU

O Koha implementa o protocolo Search/Retrieve via URL (SRU). Para mais informações sobre o protocolo consulte a página https://www.loc.gov/standards/sru/. A versão implementada é a versão 1.1.

Explain

Se deseja obter informação sobre a implementação do SRU num dado servidor, deve aceder ao ficheiro Explain efetuando um pedido ao servidor sem qualquer parâmetro. Exemplo: http://myserver.com:9999/biblios/. A resposta do servidor é um ficheiro XML parecido com o que é apresentado de seguida e que fornece informação das configurações por omissã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>

Search

Este URL : http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs é composto com os seguintes elementos:

URL base do servidor SRU : http://myserver.com:9999/biblios?
parte da pesquisa com os 3 parâmetros necessários : version, operation e query. Os parâmetros na parte da pesquisa devem estar no formato chave=valor, e devem ser combinados com o separador &.

Podem ser adicionados outros parâmetros à pesquisa, como por exemplo o maximumRecords para indicar o número máximo de registos a serem retornados pelo servidor. Ou seja, o endereço http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs&maximumRecords=5 apenas vai obter os 5 primeiros resultados do servidor.

A chave «operation» pode ter dois valores: scan ou searchRetrieve.

Se operation=searchRetrieve, então a chave de pesquisa deve ser query. Exemplo : operation=searchRetrieve&query=reefs

Se operation=scan, então a chave de pesquisa deve ser scanClause. Exemplo : operation=scan&scanClause=reefs

O ficheiro etc/zebradb/biblios/etc/bib1.att define os índices Zebra/3950 que existem no sistema. Por exemplo, encontraremos nesse ficheiro índices para o Assunto e para o Título: att 21 Subject e att 4 Title, respectivamente.

No ficheiro pqf.properties, localizado na pasta etc/zebradb/, pode verificar que um ponto acesso já utiliza o índice Subject (index.dc.subject = 1=21) enquanto outro usa o índice Title (index.dc.title = 1=4). Sabemos que é o índice Subject porque como foi verificado no ficheiro bib1.att é invocado com =1=21 no Z39.50: portanto index.dc.subject = 1=21 aponta correctamente para o índice Subject. O índice Title é invocado com =1=4, então index.dc.title = 1=4 aponta correctamente para o índice Title. Com estes dados podemos construir uma pesquisa tal como a que é efetuada na caixa de pesquisa, usando para tal o parâmetro «query»: «query=Subject=reefs and Title=coral» pesquisa como assunto o termo «reefs» e como título o termo «coral». O endereço completo seria: http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral. Se desejar limitar os resultados a 5 registos podemos usar o seguinte endereço: http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs and Title=coral&maximumRecords=5

Também é possível truncar, usar relações, etc. Essas configurações também são feitas no ficheiro pqf.properties. Pode ver por exemplo as propriedades de posição definidas como:

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

Por exemplo se quiser que a palavra «coral» esteja no início do título, é possível usar a seguinte query : http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Title=coral first

Retrieve

A pesquisa http://univ_lyon3.biblibre.com:9999/biblios?version=1.1&operation=searchRetrieve&query=coral reefs&maximumRecords=1 apenas retorna um registo. A resposta é parecido com a seguinte:

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

A auto-documentação do módulo ILS-DI é a interface mais completa. Após o módulo estar ativo, como descrito na secção preferências de sistema ILS-DI, a documentação ficará disponível no endereço https://opac.example.org/cgi-bin/koha/ilsdi.pl

Serviços JSON dos relatórios

O Koha implementa um serviço JSON sobre cada um dos relatórios guardados a partir das funcionalidades Assistente de relatórios ou Relatórios a partir do SQL.

Por omissão os relatórios são privados e apenas acessíveis a utilizadores autenticados. Se um relatórios estiver como público pode ser acedidos sem autenticação por qualquer pessoa. Esta funcionalidade apenas deve ser usada quando os dados podem ser partilhados de forma segura não contendo informação de qualquer leitor.

Os relatórios podem ser acedidos usando os seguintes endereços:

Relatórios púbicos: https://opac.example.org/cgi-bin/koha/svc/report?id=REPORTID
Relatórios não públicos: https://staff-interface.example.org/cgi-bin/koha/svc/report?id=REPORTID

Existem também alguns parâmetros adicionais que pode utilizar:

Em vez de aceder ao relatório através do REPORTID, pode também utilizar o nome do relatório: https://opac.example.org/cgi-bin/koha/svc/report?name=REPORTNAME ou https://staff-interface.example.org/cgi-bin/koha/svc/report?name=REPORTNAME
Para facilitar o desenvolvimento, existe também uma opção para gerar uma saída dos dados com anotações. Isto irá produzir um array de hashes que inclui os nomes dos campos como chaves: https://opac.example.org/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1 ou https://staff-interface.example.org/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1

Esforço na RESTful API versionada

Existe um esforço em curso para convergir as APIs acima referidas num conjunto único e versionado de endpoints RESTful modernos, documentados através da norma OpenAPI e disponibilizados, por omissão, em https://opac.example.org/api/v1/

A documentação completa para estas APIs da sua versão do Koha pode ser encontrada em api.koha-community.org.

Concessão de credenciais do cliente OAuth2

O Koha oferece suporte ao fluxo de credenciais de cliente do OAuth2 como um meio de proteger a API para uso por outros sistemas, em conformidade com os padrões atuais do setor. Mais informações sobre o padrão de fluxo de credenciais de cliente do OAuth2 podem ser encontradas aqui.

Interface de gestão de chaves API para os leitores

Para que as chaves API sejam criadas aos leitores, a preferência de sistema RESTOAuth2ClientCredentials deve estar ativa, de forma a que a opção apareça no registo do leitor.

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

O Koha disponibiliza um gerador de imagens de código de barras tanto na interface administrativa como no OPAC. Em ambos os casos, é necessário que o utilizador esteja autenticado para utilizar o serviço, de forma a evitar abusos por parte de terceiros.

Por exemplo:

https://opac.example.org/cgi-bin/koha/svc/barcode?barcode=123456789&type=UPCE

ou

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

ou

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.