Koha REST API Users Guide

From Koha Wiki
Jump to navigation Jump to search

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.

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.

Once enabled, one must generate a client_id/secret pair for a user who wishes to use the API client.

The users own permissions will be used to limit the clients authorization level.

This can be managed from the user record under the 'More' menu you will find a 'Manage API keys' option from which you can then generate new client secret pairs and revoke existing ones.

The API client can then use this client_id/secret pair to request their bearer token by posting to https:your-site.com/api/v1/oauth/token.

Example of POST request to get a token

NOTE: grant_type only has one authorized value (client_credentials) 

curl -X POST https://my.koha.url.com/api/v1/oauth/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&client_id=$XXXXXXXX&client_secret=YYYYYYYY'

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

Cookie auth

Enabled by default to allow existing user sessions to be used for API authentication. This auth mechanism should only be used by Koha itself.

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

Note: since Koha 22.05, Koha now requires the following line to return a JSON response (see bug 32637)

--header  "Content-Type: application/json"

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/' --header "Content-Type: application/json" --data-raw '{ "surname": "Acevedo" }'

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header "Content-Type: application/json" --data-raw '{ "surname": { "=": "Acevedo" } }'

Contains

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

Starts with

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

Ends with

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header "Content-Type: application/json" --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/' --header "Content-Type: application/json" --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'

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

curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header "Content-Type: application/json" --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" --header "Content-Type: application/json" --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

Pagination is done via the parameters "_per_page" and "_page". These parameters are passed was part of the URL:

https://koha.mykoha.com/api/v1/patrons?_per_page=10&_page=2

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

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Koha_REST_API_Users_Guide&oldid=34688"