Web Services

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’: Provedores de dados e Provedores de serviços. Os provedores 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 Provedores de dados. Os Provedores 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.

Atualmente, o Koha apenas funciona como Provedor 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. Visite a página http://www.oaforum.org/tutorial/english/page3.htm para consultar alguns diagramas de como o OAI-PMH funciona.

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

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

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 ver o seu ficheiro.

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
  marcxml:
     metadataPrefix: marxml
     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 ter 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 e, após o módulo estar ativo com descrito na secção ILS-DI das preferências de sistema, a documentação estará 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 um 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.

  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