Koha REST API Users Guide

From Koha Wiki

Jump to: navigation, search
Home > Documentation

Koha has an old, RESTish API, referred to as SVC. A new REST API is being added from scratch, and this page aims to inform non-Koha developers about how to develop against this new API.

Contents

Documentation

The REST API is self documenting, so you can view documentation describing the actual version you will be working with at the following URL:

https://example.com/api/v1/.html

Here is a live example, from a demo installation:

https://demo.bibkat.no/api/v1/.html

Authentication

OAuth

Can be enabled with the RESTOAuth2ClientCredentials syspref.

Basic auth

Can be enabled with the RESTBasicAuth syspref. Uses the username and password of a patron/borrower registered in Koha.

Note that RESTBasicAuth only works when using Plack; it will not work when using CGI.

Simple example in Perl

This will fetch a list of libraries from the Koha instance:

 use Modern::Perl;
 use LWP::UserAgent;
 use HTTP::Request::Common;
 
 my $domain   = 'example.com';
 my $username = 'foo';
 my $password = 'bar';
 
 my $ua = LWP::UserAgent->new();
 my $request = GET "https://$domain/api/v1/libraries";
 
 $request->authorization_basic( $username, $password );
 
 my $response = $ua->request($request);
 say $response->as_string();

Versions

Added in Bug 22132, and part of Koha from the following versions:

  • 19.05.00
  • 18.11.03

The q parameter

The "q" parameter allows for building extremely complex queries using Koha's REST API. It is based on the same syntax as Perl's DBIx::Class querying language.

It can be sent as 'q' in a URL parameter, or as the body of the request. We will be using the request body in the examples below.

Searching

Basic Matching

Exact

Exact is the default, so unless `_match` is specified, it will be as if `_match` were set to `contains`.

The following are equivalent

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": "Acevedo1" }'
curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "=": "Acevedo" } }'

Contains

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "%Acevedo%" } }'

Starts with

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "Ace%" } }'

Ends with

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "%edo" } }'

Advanced Matching

Matching on multiple parameters

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'
curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "=": "Acevedo" }, "firstname": { "=": "Henry" } }'

Filtering

Comparison Operators

The "q" above is using the "=" comparison operator for an exact match. This can be replaced with other comparisons such as ">", "<", ">=", or "<=", "-like", and "-not_like"

Pagination

Sorting

Plugins

The REST API can be extended through Koha plugins. See the Kitchen sink example plugin from ByWater for an example.

Examples

See also

Personal tools