Koha /svc/ HTTP API

From Koha Wiki
Jump to navigation Jump to search

This API was originally developed by Liblime back in the days where they where part of Koha community for its biblios web service API, but documentation for it has since dissipated from internet[1]

This API uses records in MARCXML format for which specification can be found at http://www.loc.gov/standards/marcxml/

All URLs of this REST API are available under your Koha staff interface URL.

Set up `SvcMaxreportRows` to Only return ... rows of a report requested via the reports web service.

Changes coming in Koha 24.05

In Koha 24.05, a "Csrf-Token" request header will be required for all POST requests below. The userid and password parameters have also been changed to login_userid and login_password.

The overall flow will look something like the following: 

curl -v 'http://localhost:8081/cgi-bin/koha/svc/authentication' --cookie-jar /tmp/test.cookies

This initial request generates a CGISESSID cookie linked to an anonymous session and provides a Csrf-Token in a response header. Use that cookie and that Csrf-Token value to authenticate. 

curl -v -H "Content-Type: application/x-www-form-urlencoded" -H "Csrf-Token: 4dda36756ec4f7ac178fb5500e1873b6f50cf9bc,699bc3e9fbb01ca7282bc8d847d8a018e696d327,1716342462" -XPOST -v 'http://localhost:8081/cgi-bin/koha/svc/authentication' -d "login_userid=koha&login_password=koha" --cookie /tmp/test.cookies --cookie-jar /tmp/test.cookies

At this point, you'll be issued a new CGISESSID cookie linked to an authenticated session and you'll be provided with a new Csrf-Token value, which you can use for up to 8 hours or until the end of your session (whichever is shorter). Note down this value in your code, as you'll need it for your subsequent POST requests. If you lose it for whatever reason, you can get a new Csrf-Token by using your authenticated cookie and sending a GET to /cgi-bin/koha/svc/authentication like you did in the first step. 

curl -XGET -v 'http://localhost:8081/cgi-bin/koha/svc/bib/29' --cookie /tmp/test.cookies > rec.marcxml

curl -H "Content-Type: text/xml" -H "Csrf-Token: 8e9a7f599926564aebb44a15a66ad77612465722,cbb37f24e7b8129e8d246a29889823a02b80428d,1716342476" -XPOST -v 'http://localhost:8081/cgi-bin/koha/svc/bib/29' --cookie /tmp/test.cookies --data @rec.marcxml

POST /svc/authentication

The authentication strategy for the biblios web services is as follows.

1. biblios POSTs to the authenticate API with URL-encoded form parameters 'userid' and 'password'. If the credentials belong to a valid user with the 'editcatalogue' privilege, a session cookie is returned and a Koha session created. Otherwise, an appropriate error is returned.

2. For subsequent calls to the biblios APIs, the user agent should submit the same session cookie. If the cookie is not supplied or does not correspond to a valid session, the API will redirect to this authentication API.

3. The session cookie should not be (directly) sent back to the user's web browser, but instead should be stored and submitted by biblios. 


$ curl http://koha-dev:8080/cgi-bin/koha/svc/authentication -d 'userid=svcuser&password=svcpasswd'
<?xml version='1.0' standalone='yes'?>
<response>
 <status>ok</status>
</response>

status can be one of following codes:

  • ok - user logged in
  • faild - invalid userid or password, or wrong permissions
  • maintenance - Koha needs upgrade
  • expired - session is no longer valid

GET /svc/bib_profile

Quering this service will return information about fields which are defined for biblio record. 

$ curl http://koha-dev:8080/cgi-bin/koha/svc/bib_profile -d 'userid=svcuser&password=svcpasswd'
<?xml version='1.0' standalone='yes'?>
<response>
 <auth_status>ok</auth_status>
 <bib_number>
   <subfield>c</subfield>
   <tag>999</tag>
 </bib_number>
 <mandatory_subfields>
   <subfield>
     <subfield_label>c</subfield_label>
     <tag>040</tag>
   </subfield>
   <subfield>
     <subfield_label>a</subfield_label>
     <tag>245</tag>
   </subfield>
 </mandatory_subfields>
 <mandatory_tags>
   <tag>000</tag>
   <tag>003</tag>
   <tag>005</tag>
   <tag>008</tag>
   <tag>040</tag>
   <tag>245</tag>
 </mandatory_tags>
 <reserved_tags>
   <tag>999</tag>
   <tag>942</tag>
   <tag>952</tag>
 </reserved_tags>
 <special_entry>
   <field>
     <subfield>c</subfield>
     <tag>942</tag>
   </field>
   <valid_values>
     <value>
       AVG
       <description>AV građa</description>
     </value>
     <value>
       SPE
       <description>Specijalistički rad</description>
     </value>
   </valid_values>
 </special_entry>
</response>

GET /svc/bib/$biblio

Retrieve record using biblionumber 

$ curl 'http://koha-dev:8080/cgi-bin/koha/svc/bib/5678?userid=svcuser&password=svcpasswd' > rec.marcxml

Corresponding link on Koha intranet for same record would be http://koha-dev:8080/cgi-bin/koha/catalogue/MARCdetail.pl?biblionumber=5678 and http://koha-dev/cgi-bin/koha/opac-MARCdetail.pl?biblionumber=5678

It's handy to have this two links around when you are developing against this API since they are Koha's HTML rendition of same record.

From version 3.8, appending ?items=1 to the URL will include all the item tags in the returned record.

POST /svc/bib/$biblio

Update of record is possible using POST to upload MARCXML file. Example HTTP client is attached to bug http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=7213

For this to work from other languages, you have to use HTTP client library which supports POST request and cookies. You will also need to specify correct Content-type header (text/plain or text/xml). For example, with curl: 

 # create cookie jar
 curl 'http://koha-dev:8080/cgi-bin/koha/svc/authentication?userid=svcuser&password=svcpasswd' --cookie-jar /tmp/svc.cookies
 
 # update bib 1234 from rec.marcxml file using cookie jar
 curl 'http://koha-dev:8080/cgi-bin/koha/svc/bib/1234' --cookie /tmp/svc.cookies --header "Content-type: text/xml" --data @rec.marcxml

From version 3.8, appending ?items=1 to the URL will parse all the item tags in the returned record and add them to the record in koha, or update them if the itemnumber already exists.

POST /svc/new_bib

Creation of new biblio record is possible using POST request, similar to update.

This API can also create item records from information embedded in the bib, using the tag and subfields for the default MARC framework. To enable this, pass a URL parameter called items whose value is 1.

POST /svc/import_bib

From version 3.8, creation of new biblio record is possible using POST request, similar to update. This route puts records through the staged MARC records system in Tools, so they can be reverted or label batches created for them.

Fields from the Stage MARC Records for Import Tool can be appended to the URL, along with the additional options ?import_mode=direct and framework=BK

Example /svc/ client

There is example of client attached to bug http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=7213

It comes with built-in pod documentation which is available with perldoc misc/migration_tools/koha-svc.pl

Same client can be used from other scripts if used with require "koha-svc.pl" (since it's .pl script instead of .pm we have to require it instead of using use).

Search over HTTP

At first sight, it might seem that one important part of API is missing: search. How should we locate interesting records and find its biblio number?

Fortunately Zebra provides us with HTTP based SRU API documented at http://www.indexdata.com/zebra/doc/zebrasrv.html#zebrasrv-sru

Suggested default query (with a little bit cleanup to be standard SRU) is something like: 

 http://koha-dev:9999/biblios?version=1.1&operation=searchRetrieve&query=human&startRecord=1&maximumRecords=10&recordSchema=marcxml

to retrieve first 10 records. Please note *recordSchema* parameter which requests response in MARCXML format.

Alternative standard records schemes are available at http://www.loc.gov/standards/sru/resources/schemas.html if MARCXML isn't your favorite format.

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Koha_/svc/_HTTP_API&oldid=34312"