Koha REST API Users Guide

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 , 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==
* REST API: Checking username and password
* Blogpost on integration of Koha and Coral, code (PHP)
* Using the REST API (Koha advent calendar 2020)
* Passing token in KOHA using REST API php (Stack Overflow)
==See also==
* REST API in Bugzilla
* Rest Api HowTo
* Coding Guidelines - API
Category:Documentation