source/webservices.rst

   1 .. include:: images.rst
   2
   3 Web Services
   4 ============
   5
   6 Koha provides a number of APIs allowing access to it's data and functions.
   7
   8 .. _oai-pmh-label:
   9
  10 OAI-PMH
  11 -----------------------------
  12
  13 For the Open Archives Initiative-Protocol for Metadata Harvesting
  14 (OAI-PMH) there are two groups of 'participants': Data Providers and
  15 Service Providers. Data Providers (open archives, repositories) provide
  16 free access to metadata, and may, but do not necessarily, offer free
  17 access to full texts or other resources. OAI-PMH provides an easy to
  18 implement, low barrier solution for Data Providers. Service Providers
  19 use the OAI interfaces of the Data Providers to harvest and store
  20 metadata. Note that this means that there are no live search requests to
  21 the Data Providers; rather, services are based on the harvested data via
  22 OAI-PMH.
  23
  24 Koha at present can only act as a Data Provider. It can not harvest from
  25 other repositories. The biggest stumbling block to having Koha harvest
  26 from other repositories is that MARC is the only metadata format that
  27 Koha indexes natively. Visit
  28 http://www.oaforum.org/tutorial/english/page3.htm for diagrams of how
  29 OAI-PMH works.
  30
  31 By default Koha won't include item information in OAI-PMH result sets,
  32 but they can be added by using the include_items option in the a
  33 configuration file linked from :ref:`OAI-PMH:ConfFile`.
  34
  35 Learn more about OAI-PMH at: http://www.openarchives.org/pmh/
  36
  37 To enable OAI-PMH in Koha edit the :ref:`OAI-PMH` preference.
  38 Once enabled you can visit http://YOURKOHACATALOG/cgi-bin/koha/oai.pl to
  39 see your file.
  40
  41 .. _sample-oai-conf-file-label:
  42
  43 Sample OAI Conf File
  44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  45
  46 ::
  47
  48   format:
  49     vs:
  50       metadataPrefix: vs
  51       metadataNamespace: http://veryspecial.tamil.fr/vs/format-pivot/1.1/vs
  52       schema: http://veryspecial.tamil.fr/vs/format-pivot/1.1/vs.xsd
  53       xsl_file: /usr/local/koha/xslt/vs.xsl
  54     marcxml:
  55        metadataPrefix: marxml
  56        metadataNamespace: http://www.loc.gov/MARC21/slim http://www.loc.gov/standards/marcxml/schema/MARC21slim
  57        schema: http://www.loc.gov/MARC21/slim http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd
  58        include_items: 1
  59     oai_dc:
  60        metadataPrefix: oai_dc
  61        metadataNamespace: http://www.openarchives.org/OAI/2.0/oai_dc/
  62        schema: http://www.openarchives.org/OAI/2.0/oai_dc.xsd
  63        xsl_file: /usr/local/koha/koha-tmpl/intranet-tmpl/xslt/UNIMARCslim2OAIDC.xsl
  64
  65 .. _sru-server-label:
  66
  67 SRU server
  68 -----------------------------
  69
  70 Koha implements the Search/Retrieve via URL (SRU) protocol. More
  71 information about the protocol itself can be found at
  72 http://www.loc.gov/standards/sru/. The version implemented is version
  73 1.1.
  74
  75 .. _explain-label:
  76
  77 Explain
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 If you want to have information about the implementation of SRU on a
  81 given server, you should have access to the Explain file using a request
  82 to the server without any parameter. Like
  83 http://myserver.com:9999/biblios/. The response from the server is an
  84 XML file that should look like the following and will give you
  85 information about the default settings of the SRU server.
  86
  87 ::
  88
  89                    <zs:explainResponse>
  90                         <zs:version>1.1</zs:version>
  91                         <zs:record>
  92                              <zs:recordSchema>http://explain.z3950.org/dtd/2.0/</zs:recordSchema>
  93                              <zs:recordPacking>xml</zs:recordPacking>
  94                              <zs:recordData>
  95                              <explain xml:base="zebradb/explain-biblios.xml">
  96                              <!--
  97                              try stylesheet url: http://./?stylesheet=docpath/sru2.xsl
  98                              -->
  99                         <serverInfo protocol="SRW/SRU/Z39.50">
 100                              <host>biblibre</host>
 101                              <port>9999</port>
 102                              <database>biblios</database>
 103                         </serverInfo>
 104                         <databaseInfo>
 105                              <title lang="en" primary="true">Koha 3 Bibliographic SRU/SRW/Z39.50 server</title>
 106                              <description lang="en" primary="true">Koha 3 Bibliographic Server</description>
 107                              <links>
 108                                   <sru>http://biblibre:9999</sru>
 109                              </links>
 110                         </databaseInfo>
 111                         <indexInfo>
 112                              <set name="cql" identifier="info:srw/cql-context-set/1/cql-v1.1">
 113                                   <title>CQL Standard Set</title>
 114                              </set>
 115                              <index search="true" scan="true" sort="false">
 116                              <title lang="en">CQL Server Choice</title>
 117                              <map>
 118                                   <name set="cql">serverChoice</name>
 119                              </map>
 120                         <map>
 121                            <attr type="1" set="bib1">text</attr>
 122                            </map>
 123                       </index>
 124                   <index search="true" scan="true" sort="false">
 125                      <title lang="en">CQL All</title>
 126                          <map>
 127             <name set="cql">all</name>
 128             </map>
 129             <map>
 130             <attr type="1" set="bib1">text</attr>
 131             </map>
 132             </index>
 133             <!-- Record ID index -->
 134             <index search="true" scan="true" sort="false">
 135             <title lang="en">Record ID</title>
 136             <map>
 137             <name set="rec">id</name>
 138             </map>
 139             <map>
 140             <attr type="1" set="bib1">rec:id</attr>
 141             <attr type="4" set="bib1">3</attr>
 142             </map>
 143             </index>
 144
 145
 146 .. _search-label:
 147
 148 Search
 149 ~~~~~~~~~~~~~~~~~~~~~~~~
 150
 151 This url :
 152 http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs
 153 is composed of the following elements:
 154
 155 -  base url of the SRU server : http://myserver.com:9999/biblios?
 156
 157 -  search part with the 3 required parameters : version, operation and
 158    query. The parameters within the search part should be of the
 159    key=value form, and can be combined with the & character.
 160
 161 One can add optional parameters to the query, for instance
 162 maximumRecords indicating the maximum number of records to be returned
 163 by the server. So
 164 http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=reefs&maximumRecords=5
 165 will only get the first 5 results results from the server.
 166
 167 http://www.loc.gov/standards/sru/sru1-1archive/search-retrieve-operation.html
 168 gives more details about the search operations and in particular the
 169 list of optional parameters for searching.
 170
 171 The "operation" key can take two values: scan or searchRetrieve.
 172
 173 If operation=searchRetrieve, then the search key should be query. As in
 174 : operation=searchRetrieve&query=reefs
 175
 176 If operation=scan, then the search key should be scanClause. As in :
 177 operation=scan&scanClause=reefs
 178
 179 etc/zebradb/biblios/etc/bib1.att defines Zebra/3950 indexes that exist
 180 on your system. For instance you'll see that we have indexes for Subject
 181 and for Title: att 21 Subject and att 4 Title respectively.
 182
 183 In the pqf.properties file located under etc/zebradb/pqf.properties I
 184 see that an access point already uses my Subject index (index.dc.subject
 185 = 1=21) while another uses my Title index (index.dc.title = 1=4) I know
 186 this is my Subject index because as I've seen just before in my bib1.att
 187 file, it's called with =1=21 in Z3950: so index.dc.subject = 1=21
 188 correctly points to my Subject index. And Title was called with 1=4 so
 189 index.dc.title = 1=4 correctly points to my Title index. I can now
 190 construct my query just like I would in a search box, just preceding it
 191 with the "query" key: query=Subject=reefs and Title=coral searches
 192 "reefs" in the subject and "coral" in the title. The full url would be
 193 http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs
 194 and Title=coral If I want to limit the result set to just 5 records, I
 195 can do
 196 http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Subject=reefs
 197 and Title=coral&maximumRecords=5
 198
 199 I can also play with truncate, relations, etc. Those are also defined in
 200 my pqf.properties file. I can see for instance the position properties
 201 defined as:
 202
 203 ::
 204
 205                    position.first              = 3=1 6=1
 206                   # "first in field"
 207                    position.any                = 3=3 6=1
 208                      # "any position in field"
 209
 210
 211 So as an example if I want "coral" to be at the beginning of the title,
 212 I can do this query :
 213 http://myserver.com:9999/biblios?version=1.1&operation=searchRetrieve&query=Title=coral
 214 first
 215
 216 .. _retrieve-label:
 217
 218 Retrieve
 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 220
 221 My search for
 222 http://univ\_lyon3.biblibre.com:9999/biblios?version=1.1&operation=searchRetrieve&query=coral
 223 reefs&maximumRecords=1 retrieves just on record. The response looks like
 224 this:
 225
 226 ::
 227
 228               <zs:searchRetrieveResponse>
 229     <zs:version>1.1</zs:version>
 230     <zs:numberOfRecords>1</zs:numberOfRecords>
 231     <zs:records>
 232     <zs:record>
 233     <zs:recordPacking>xml</zs:recordPacking>
 234     <zs:recordData>
 235     <record xsi:schemaLocation="http://www.loc.gov/MARC21/slim http://www.loc.gov/ standards/marcxml/schema/MARC21slim.xsd">
 236     <leader> cam a22 4500</leader>
 237     <datafield tag="010" ind1=" " ind2=" ">
 238     <subfield code="a">2-603-01193-6</subfield>
 239     <subfield code="b">rel.</subfield>
 240     <subfield code="d">159 F</subfield>
 241     </datafield>
 242     <datafield tag="020" ind1=" " ind2=" ">
 243     <subfield code="a">FR</subfield>
 244     <subfield code="b">00065351</subfield>
 245     </datafield>
 246     <datafield tag="101" ind1="1" ind2=" ">
 247     <subfield code="c">ita</subfield>
 248     </datafield>
 249     <datafield tag="105" ind1=" " ind2=" ">
 250     <subfield code="a">a z 00|y|</subfield>
 251     </datafield>
 252     <datafield tag="106" ind1=" " ind2=" ">
 253     <subfield code="a">r</subfield>
 254     </datafield>
 255     <datafield tag="100" ind1=" " ind2=" ">
 256     <subfield code="a">20091130 frey50 </subfield>
 257     </datafield>
 258     <datafield tag="200" ind1="1" ind2=" ">
 259     <subfield code="a">Guide des récifs coralliens / A Guide to Coral Reefs</subfield>
 260     <subfield code="b">Texte imprimé</subfield>
 261     <subfield code="e">la faune sous-marine des coraux</subfield>
 262     <subfield code="f">A. et A. Ferrari</subfield>
 263     </datafield>
 264     <datafield tag="210" ind1=" " ind2=" ">
 265     <subfield code="a">Lausanne</subfield>
 266     <subfield code="a">Paris</subfield>
 267     <subfield code="c">Delachaux et Niestlé</subfield>
 268     <subfield code="d">cop. 2000</subfield>
 269     <subfield code="e">impr. en Espagne</subfield>
 270     </datafield>
 271     <datafield tag="215" ind1=" " ind2=" ">
 272     <subfield code="a">287 p.</subfield>
 273     <subfield code="c">ill. en coul., couv. ill. en coul.</subfield>
 274     <subfield code="d">20 cm</subfield>
 275     </datafield>
 276     ......
 277     <idzebra>
 278     <size>4725</size>
 279     <localnumber>2</localnumber>
 280     <filename>/tmp/nw10BJv9Pk/upd_biblio/exported_records</filename>
 281     </idzebra>
 282     </record>
 283     </zs:recordData>
 284     <zs:recordPosition>1</zs:recordPosition>
 285     </zs:record>
 286     </zs:records>
 287     </zs:searchRetrieveResponse>
 288
 289 .. _ils-di-label:
 290
 291 ILS-DI
 292 ------
 293
 294 As of writing, the self documenting ILS-DI is the most complete interface and
 295 after it has been enabled as described in the :ref:`ils-di-label`system
 296 preferences section the documentation should be available at
 297 https://YOURKOHACATALOG/cgi-bin/koha/ilsdi.pl
 298
 299 .. _json-reports-services-label:
 300
 301 JSON reports services
 302 ----------------------------------
 303
 304 Koha implements a JSON reports service for every report saved
 305 using the :ref:`Guided Reports Wizard <guided-report-wizard-label>`
 306 or :ref:`Report from SQL <report-from-sql-label>` features.
 307
 308 By default reports will be non-public and only accessible by authenticated
 309 users. If a report is explicitly set to *public* it will be accessible
 310 without authentication by anyone. This feature should only be used
 311 when the data can be shared safely not containing any patron information.
 312
 313 The reports can be accessed using the following URLs:
 314
 315 -  Public reports
 316
 317    -  OpacBaseURL/cgi-bin/koha/svc/report?id=REPORTID
 318
 319 -  Non-public reports
 320
 321    -  StaffBaseURL/cgi-bin/koha/svc/report?id=REPORTID
 322
 323 There are also some additional parameters available:
 324
 325 -  Instead of accessing the report by REPORTID you can also use the
 326    report's name:
 327
 328    -  .../cgi-bin/koha/svc/report?name=REPORTNAME
 329
 330 -  For easier development there is also an option to generate an
 331    annotated output of the data. It will generate an array of hashes
 332    that include the field names as keys.
 333
 334    -  .../cgi-bin/koha/svc/report?name=REPORTNAME&annotated=1
 335
 336 .. _api-rest-label:
 337
 338 Versioned RESTful API Effort
 339 ----------------------------
 340
 341 There is an ongoing effort to converge the APIs above into a single versioned
 342 set of modern RESTful endpoints documented using the OpenAPI standard and
 343 available by default under https://YOURKOHACATALOG/api/v1/
 344
 345 .. _oauth2-client-credentials-grant-label:
 346
 347 OAuth2 client credentials grant
 348 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 349
 350 Koha supports the OAuth2 client credentials grant as a means to secure the API
 351 for using it from other systems to adhere to current industry standards.
 352 More information on the OAuth2 client credentials grant standard `can be found
 353 here <https://auth0.com/docs/api-auth/grant/client-credentials>`_.
 354
 355 API key management interface for patrons
 356 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 357
 358 In order for API keys to be create for patrons, the system preference
 359 :ref:`RESTOAuth2ClientCredentials` **must** be enabled for the option to appear
 360 in a patron record.
 361
 362 1. Navigate to a patron record and select *More > Manage API keys*
 363
 364   |image1336|
 365
 366 2. If no API keys exist for a patron there will be a message prompting to
 367    generate a client id/secret pair
 368
 369   |image1337|
 370
 371 3. Enter a description for the client id/secret pair and click Save
 372
 373   |image1338|
 374
 375 4. Koha will generate a client id/secret pair for use to connect to Koha from
 376    other third-party systems as an authenticated client
 377
 378    |image1339|
 379
 380 5. Clicking the Revoke button next to an API credential pair will render the
 381    specific credential pair inactive until reactivated