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

The options are:

xsl_file: Path to an XSLT file that will be used for transforming the Koha MARCXML data into the needed structure/format. It can be useful, for example, if you need some specific Dublin Core fields to be generated instead of just the default ones.
include_items: If set to 1, item information will be included in the response according to the MARC framework’s mapping.
expanded_avs: If set to 1, all coded values will the expanded with descriptions. This includes library names, item type descriptions, authorized value descriptions and classification source descriptions.

All these options can be used with different metadataPrefix entries, allowing the consumers to request one or the other.

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>

Pesquisar

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

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.