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: http://www.openarchives.org/pmh/

Atualmente, o Koha apenas funciona como Fornecedor de Dados. Não pode agregar informação de outros repositórios. O maior obstáculo para que o Koha agregue informação de outros repositórios é que o MARC é o único formato de metadados que o Koha indexa de forma nativa.

Para ativar o OAI-PMH, edite a preferência de sistema OAI-PMH. Assim que ativar a preferência aceda a http://YOURKOHACATALOG/cgi-bin/koha/oai.pl para verificar o serviço.

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 exemplo de configuração tem os prefixos marc21 e marcxml, porque o marc21 é o prefixo de metadados recomendado nas Diretrizes OAI-PMH [https://www.openarchives.org/OAI/2.0/guidelines-marcxml.htm], enquanto o marcxml é usado desde nas versões anteriores ao Koha 23.11 (o suporte para marc21 foi adicionado no Koha 17.05).

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

Servidor SRU

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

Explicação

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>

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 com descrito na secção ref:preferências de sistema ILS-DI <webservices-ils-di-system-preferences-label>, 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 ref:Assistente de relatórios <guided-report-wizard-label> 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/

Concessão de credenciais do cliente OAuth2

O Koha suporta a concessão de credenciais do cliente OAuth2 como um meio de proteger a API de ser usada por outros sistema e para aderir aos padrões atuais do setor. Pode encontrar mais informações sobre o OAuth2 aqui [https://auth0.com/docs/api-auth/grant/client-credentials].

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.

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

image1336

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

image1337

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

image1338

  1. O Koha vai gerar um par identificador/segredo para ser usado na conexão ao Koha a partir de outros sistemas como cliente autenticado

    image1339

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