Serviços web

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

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.

Para habilitar o OAI-PMH no Koha edite a preferência OAI-PMH. Uma vez que ela esteja habilitada você pode visitar o http://SEUCATÁLOGO/cgi-bin/koha/oai.pl para ver seu arquivo.

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.

Observe que o arquivo de conf da amostra abaixo contém marc21 e marcxml, porque marc21 é o prefixo de metadados recomendado pelas diretrizes OAI-PMH enquanto marcxml foi o único na amostra antes do Koha 23.11 (e o suporte para o marc21 foi adicionado no Koha 17.05).

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 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://YOURKOHACATALOG/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úblicos
- OpacBaseURL/cgi-bin/koha/svc/report?id=REPORTID
Relatórios privados
- StaffBaseURL/cgi-bin/koha/svc/report?id=REPORTID

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

Em vez de aceder ao relatórios pelo REPORTID pode usar o nome do relatório:
- …/cgi-bin/koha/svc/report?name=REPORTNAME
Para facilitar desenvolvimentos adicionais, existe uma opção para gerar dados de saída anotados. Irá gerar um lista de matrizes que incluem os nomes dos campos como chaves.
- …/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1

Esforço na RESTful API versionada

Há um esforço contínuo para convergir as APIs acima descritas, num único conjunto versionado de endpoints RESTful modernos e documentados usando o padrão OpenAPI e disponível por omissão no endereço https://YOURKOHACATALOG/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 fornece um gerador de imagem de código de barras no interface dos técnicos e no interface público. Necessitam de estar autenticados para usar o serviço, de forma a prevenir o abuso de fontes externas.

Por exemplo:

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

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