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

Documentation for the REST API is available here: https://api.koha-community.org/

The REST API is also 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" } }'
curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "-or": [ { "surname": { "-like": "Acev%" } }, { "firstname": { "-like": "Hen%" } } ] }'

Matching across multiple tables

If you are embedding related Koha data in your query, you can query across the related data.

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header "x-koha-embed: extended_attributes" --data-raw '{ "extended_attributes.code": "internet", "extended_attributes.attribute": "1" }'

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