Serviços web

O Koha oferece uma série de APIs que permitem 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 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

No momento em que este manual foi escrito, o ILS-DI autodocumentado é a interface mais completa. Depois de habilitado conforme descrito na seção ILS-DI system preferences, a documentação deve estar disponível em https://SEUCATALOGO/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:

Relatórios públicos
- OpacBaseURL/cgi-bin/koha/svc/report?id=REPORTID
Relatórios não públicos
- StaffBaseURL/cgi-bin/koha/svc/report?id=REPORTID

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

Em vez de acessar o relatório pelo REPORTID, você também pode usar o nome do relatório:
- …/cgi-bin/koha/svc/report?name=REPORTNAME
Para facilitar o desenvolvimento, também há uma opção para gerar uma saída anotada dos dados. Ela irá gerar um array de hashes que inclui os nomes dos campos como chaves.
- …/cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1

Esforço de API RESTful versionada

Há um esforço em andamento para convergir as APIs acima em um único conjunto versionado de endpoints RESTful modernos, documentados usando o padrão OpenAPI e disponíveis por padrão em https://YOURKOHACATALOG/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 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.