Talk:Koha /svc/ HTTP API

Proposed documentation for Bug 13607 - patron management API

Patron Management API

Purpose

This provides an API with which simple patron management can be performed. The intention is that external member management systems can talk to Koha to ensure that its database is up to date.

Authentication

It is required that authentication is performed prior to using this API, using the standard svc method. While authentication only requires the editcatalogue permission, access to the patron management API will also require the borrowers permission.

Create and Updating a Patron

POST /cgi-bin/koha/svc/members/upsert

Creates or updates a patron. The parameters are the fields from the Koha borrower table, and any extended attributes defined in Koha. Requires an authenticated session. The borrower table fields are defined and described in the community documentation: http://schema.koha-community.org/tables/borrowers.html

An additional field must be provided in the request: matchField. This provides the field that should be used to determine uniqueness, for example, email. If a borrower with this field already exists in the database, then their record will be updated to match the provided information. If no borrower exists, then one will be created.

To clear a field, provide an empty XML element for that field.

Date values must be ISO form: YYYY-MM-DD.

Boolean values (referred to as bit in the schema) must be 1 (for true) or 0 (for false.)

A borrowernumber field may be provided and used for matching, Koha will accept this, however attempting to define or update a borrowernumber will be silently ignored.

An extended attribute field may be provided for matching.

Extended attributes are custom to the configuration of Koha by the library staff, and required values should be agreed with them. It is strongly recommended that, if an extended attribute is to be used, that it is defined to be unique.

If an extended attribute is included as part of an update, it will replace any attributes for that borrower with a matching code. Only a single value can be provided for each extended attribute per borrower.

Specifying a matchField that is not indexed in the database may incur significant performance penalty, it is recommended that an index be added to any field that is to be matched on.

If setting passwords through this call, then they must be of the hashed form that Koha stores in its database. Code that generates this form (salted bcypt) can be found in the Koha source code, in the Koha::AuthUtils module.

Return

On success, this returns a status OK code with:

• a borrowernumber element containing the system-allocated ID of the new account,
• a createOrUpdate element that contains either create or update, depending on whether a new record was created, or an existing one updated.

Error cases include:

• a matchField that doesn't match either a field in the borrowers table, or an extended attribute.

Delete a Patron

POST /cgi-bin/koha/svc/members/delete

Deletes a user. A field and a value must be provided to match against. The field may also be an extended attribute code. If any borrower can't be deleted, then no borrowers will be deleted.

Return

On success, this returns a status OK code, and a count of the deleted borrowers. This count may be zero.

On error, this returns a failed status, and a comma-separated list of the borrowers with charges and issues outstanding.

Error cases include:

• a matchField that doesn't match either a field in the borrowers table, or an extended attribute.
• a borrower can't be deleted because they have outstanding issues or charges against their account.

Example API Usage Session

The following is an example of accessing this API using the 'curl' command line tool. All the parameters are form-encoded and sent as the body of a POST request.

$ curl -i  http://usertest-intra.koha.catalystdemo.net.nz/cgi-bin/koha/svc/authentication -d 'userid=testuser&password=password'
HTTP/1.1 200 OK
Date: Wed, 21 Jan 2015 04:19:49 GMT
Server: Apache/2.2.16 (Debian)
Set-Cookie: CGISESSID=2ab0de999ff93006b56e2d0e4f27a89c; path=/; HttpOnly
Vary: User-Agent,Accept-Encoding
Transfer-Encoding: chunked
Content-Type: text/xml; charset=ISO-8859-1

<?xml version='1.0' standalone='yes'?>
<response>
  <status>ok</status>
</response>

$ curl -b CGISESSID=2ab0de999ff93006b56e2d0e4f27a89c http://usertest-intra.koha.catalystdemo.net.nz/cgi-bin/koha/svc/members/upsert -d 'matchField=cardnumber&cardnumber=98765&categorycode=CA&branchcode=WLGTN&firstname=Joe'
<?xml version="1.0" encoding="UTF-8"?>
<response><status>failed</status><type>data</type><message>Critical field missing (create): surname
</message></response>

$ curl -b CGISESSID=2ab0de999ff93006b56e2d0e4f27a89c http://usertest-intra.koha.catalystdemo.net.nz/cgi-bin/koha/svc/members/upsert -d 'matchField=cardnumber&cardnumber=98765&categorycode=CA&branchcode=WLGTN&firstname=Joe&surname=Bloggs'
<?xml version="1.0" encoding="UTF-8"?>
<response><status>ok</status><borrowernumber>37718</borrowernumber><createOrUpdate>create</createOrUpdate></response>

$ curl -b CGISESSID=2ab0de999ff93006b56e2d0e4f27a89c http://usertest-intra.koha.catalystdemo.net.nz/cgi-bin/koha/svc/members/upsert -d 'matchField=cardnumber&cardnumber=98765&categorycode=CA&branchcode=WLGTN&firstname=Joe&surname=Bloggs&userid=joe.bloggs'
<?xml version="1.0" encoding="UTF-8"?>
<response><status>ok</status><borrowernumber>37718</borrowernumber><createOrUpdate>update</createOrUpdate></response>

$ curl -b CGISESSID=2ab0de999ff93006b56e2d0e4f27a89c http://usertest-intra.koha.catalystdemo.net.nz/cgi-bin/koha/svc/members/delete -d 'userid=joe.bloggs'
<?xml version="1.0" encoding="UTF-8"?>
<response><deletedcount>1</deletedcount><status>ok</status></response>

$ curl -b CGISESSID=2ab0de999ff93006b56e2d0e4f27a89c http://usertest-intra.koha.catalystdemo.net.nz/cgi-bin/koha/svc/members/delete -d 'userid=joe.bloggs'
<?xml version="1.0" encoding="UTF-8"?>
<response><deletedcount>0</deletedcount><status>ok</status></response>