Koha REST API (1)

The API supports two sets of endpoints, one targetted at library staff and the other at at library users.

Those endpoints under the /public path are aimed at delivering functionality tailored to library users and offer a more restricted set of functions, overrides and data in thier responses for data privacy and library policy reasons. Many of these endpoints do not require authentication for fetching public data, though an authenticated session will expose additional options and allow users to see more data where it is part of their own record.

All other endpoints are targetted at the staff interface level and allow for additional functionality and a more unrestricted view of data. These endpoints, however, have a level of redaction built in for resources that the api consumer should not have access to. For example, user data for users who do not belong to the same library or library group of your api user will be reduced to just minimum neccesary for a valid response. Object keys will be consistent for all responses, but their values may be removed depending on access.

The API supports the following authentication mechanisms

• HTTP Basic authentication
• OAuth2 (client credentials grant)
• Cookie-based

Both Basic authentication and the OAuth2 flow, need to be enabled by system preferences.

The API uses existing user profiles to restrict access to resources based on user permissions and the library the API user is assigned to. This may result, at times, in resources being returned in a redacted form with all keys present but sensative values nulled.

We do not yet support OAuth Scopes or the Authorization Code grant flow.

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "error": "Current settings prevent the passed due date to be applied",
  "error_code": "invalid_due_date"
}

Note: Some routes might offer additional attributes in their error responses but that"s subject to change and thus not documented.

The API allows for some advanced response filtering using a JSON based query syntax. The query can be added to the requests:

• as a query parameter q=
• in the request body

For simple field equality matches we can use { "fieldname": "value" } where the fieldname matches one of the fields as described in the particular endpoints response object.

We can refine that with more complex matching clauses by nesting a the clause into the object; { "fieldname": { "clause": "value" } }.

Available matching clauses include =, !=, <, >, <=, >= and -not. We also support -like and -not_like string comparisons with % used to denote wildcards, thus you can pass { "fieldname": { "-like": "value%" } } to do a 'starts with' string match for example.

We can filter on multiple fields by adding them to the JSON respresentation. Adding at HASH level will result in an "AND" query, whilst combinding them in an ARRAY will result in an "OR" query: { "field1": "value2", "field2": "value2" } will filter the response to only those results with both field1 containing value2 AND field2 containing value2 for example.

There is a collection of special operators also available to you, including:

• -in - Expects an array of values to perform an OR match against
• -not_in - Expects an array of values to perform a NOR match against
• -between - Expects two values which the value of the field is expected to fall between
• -not_between - Expects two values which the value of the field is expected to fall outside of
• -ident - Expects a second field name to match the two field values against
• -regexp - Expects a perl compatible regular expression for which the value should match

Logic and nesting is also supported and you may use -and and -or to change the logic of an ARRAY or HASH as described above.

Additionally, if you are requesting related data be embedded into the response one can query on the related data using dot notation in the field names.

Examples

The following request would return any patron with firstname "Henry" and lastname "Acevedo";

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

The following request would return any patron whose lastname begins with "Ace";

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

The following request would return any patron whose lastname is "Acevedo" OR "Bernardo"

curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'

The following request embeds the related patron extended attributes data and filters on it.

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" }'

x-koha-embed

This optional header allows the api consumer to request additional related data to be returned in the api response. It also allows for cross referencing in the queries as described above. It accepts a comma delimited list of relation names.

Relations may on occasion also support dot delimited nesting to allow traversal.

x-koha-library

This optional header should be passed to give your api request a library context; If it is not included in the request, then the request context will default to using your api comsumer"s assigned home library.

Manage additional fields

Manage article requests

Manage authorised value categories

Manage authorised values

Manage batch import profiles

Manage baskets for the acquisitions module

Manage Authority records

Manage bibliographic records