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>
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.
O endereço http://www.loc.gov/standards/sru/sru1-1archive/search-retrieve-operation.html fornece mais detalhes sobre as operações de pesquisa e em particular a lista de parâmetros adicionais.
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 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 [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.
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
Barcode image generator
Koha provides a barcode image generator on both the staff interface and the public interface. Both require a user to be logged in to use the service, to prevent abuse by third parties.
- For example::
/cgi-bin/koha/svc/barcode?barcode=123456789&type=UPCE
The URL above will generate a barcode image for the barcode “123456789”, using the UPCE barcode format.
The available barcode types are: * Code39 * UPCE * UPCA * QRcode * NW7 * Matrix2of5 * ITF * Industrial2of5 * IATA2of5 * EAN8 * EAN13 * COOP2of5
If no type is specified, Code39 will be used.
By default, the barcode image will contain the text of the barcode as well. If this is not desired, the parameter “notext” may be passed to supress this behavior.
- For example::
/cgi-bin/koha/svc/barcode?barcode=123456789¬ext=1
will generate a barcode image 123456789 without the text “123456789” below it.
This service can be used to embed barcode images into slips and notices printed from the browser, and to embed a patron cardnumber into the OPAC, among other possibilities.