Main Koha release repository
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

194 lines
5.5 KiB

swagger: "2.0"
basePath: /api/v1
$ref: paths.json
$ref: definitions.json
$ref: parameters.json
$ref: x-primitives.json
title: Koha REST API
version: "1"
name: GPL v3,
name: Koha Development Team
description: |
## Introduction
This API is documented in **OpenAPI format**.
## Authentication
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.
## Errors
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": "patron not found"
Note: Some routes might offer additional attributes in their error responses but that's
subject to change and thus not documented.
## Filtering responses
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
* in a special header `x-koha-query`
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 ">", "<", ">=", "<=", "-like", and "-not_like".
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` wilth 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.
### Examples
The following request would return any patron with firstname "Henry" and lastname "Acevedo";
`curl -u koha:koha --request GET '' --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'`
The following request would return any patron whose lastname begins with "Ace";
`curl -u koha:koha --request GET '' --data-raw '{ "surname": { "-like": "Ace%" }'`
The following request would return any patron whilse lastname is 'Acevedo' OR 'Bernardo'
`curl -u koha:koha --request GET '' --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'`
## Special headers
### 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.
- name: "article_requests"
x-displayName: Article requests
description: |
Manage article requests
- name: "biblios"
x-displayName: Biblios
description: |
Manage bibliographic records
- name: "cashups"
x-displayName: Cashups
description: |
Manage cash register cashups
- name: "checkouts"
x-displayName: Checkouts
description: |
Manage checkouts
- name: "circulation_rules"
x-displayName: Circulation rules
description: |
Manage circulation rules
- name: "cities"
x-displayName: Cities
description: |
Manage cities
- name: "clubs"
x-displayName: Clubs
description: |
Manage patron clubs
- name: "funds"
x-displayName: Funds
description: |
Manage funds for the acquisitions module
- name: "holds"
x-displayName: Holds
description: |
Manage holds
- name: "illbackends"
x-displayName: ILL backends
description: |
Manage ILL module backends
- name: "illrequests"
x-displayName: ILL requests
description: |
Manage ILL requests
- name: "items"
x-displayName: Items
description: |
Manage items
- name: "libraries"
x-displayName: Libraries
description: |
Manage libraries
- name: "macros"
x-displayName: Macros
description: |
Manage macros
- name: "orders"
x-displayName: Orders
description: |
Manage acquisition orders
- name: "oauth"
x-displayName: "OAuth"
description: |
Handle OAuth flows
- name: "patrons"
x-displayName: Patrons
description: |
Manage patrons
- name: "quotes"
x-displayName: Quotes
description: |
Manage quotes
- name: "return_claims"
x-displayName: Return claims
description: |
Manage return claims
- name: "rotas"
x-displayName: Rotas
description: |
Manage rotas
- name: "smtp_servers"
x-displayName: SMTP servers
description: |
Manage SMTP servers configurations
- name: "transfer"
x-displayName: Transfer limits
description: |
Manage transfer limits
- name: "suggestions"
x-displayName: "Purchase suggestions"
description: |
Manage purchase suggestions
- name: "vendors"
x-displayName: "Vendors"
description: |
Manage vendors for the acquisitions module
- name: "batch_import_profiles"
x-displayName: Batch import profiles
description: |
Manage batch import profiles