Koha /svc/ HTTP API

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
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. (Bug 38826 prevents fetching a new token from /cgi-bin/koha/svc/authentication for the current session.) 
 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.
Category:Documentation