Main Koha release repository https://koha-community.org
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.
 
 
 
 
 
 

595 lines
20 KiB

---
swagger: "2.0"
basePath: /api/v1
definitions:
account_line:
$ref: ./definitions/account_line.yaml
advancededitormacro:
$ref: ./definitions/advancededitormacro.yaml
allows_renewal:
$ref: ./definitions/allows_renewal.yaml
basket:
$ref: ./definitions/basket.yaml
cashup:
$ref: ./definitions/cashup.yaml
checkout:
$ref: ./definitions/checkout.yaml
checkouts:
$ref: ./definitions/checkouts.yaml
circ-rule-kind:
$ref: ./definitions/circ-rule-kind.yaml
city:
$ref: ./definitions/city.yaml
error:
$ref: ./definitions/error.yaml
fund:
$ref: ./definitions/fund.yaml
hold:
$ref: ./definitions/hold.yaml
holds:
$ref: ./definitions/holds.yaml
ill_backend:
$ref: ./definitions/ill_backend.yaml
ill_backends:
$ref: ./definitions/ill_backends.yaml
import_batch_profile:
$ref: ./definitions/import_batch_profile.yaml
import_batch_profiles:
$ref: ./definitions/import_batch_profiles.yaml
import_record_match:
$ref: ./definitions/import_record_match.yaml
invoice:
$ref: ./definitions/invoice.yaml
item:
$ref: ./definitions/item.yaml
library:
$ref: ./definitions/library.yaml
order:
$ref: ./definitions/order.yaml
patron:
$ref: ./definitions/patron.yaml
patron_account_credit:
$ref: ./definitions/patron_account_credit.yaml
patron_balance:
$ref: ./definitions/patron_balance.yaml
patron_extended_attribute:
$ref: ./definitions/patron_extended_attribute.yaml
quote:
$ref: ./definitions/quote.yaml
return_claim:
$ref: ./definitions/return_claim.yaml
smtp_server:
$ref: ./definitions/smtp_server.yaml
suggestion:
$ref: ./definitions/suggestion.yaml
transfer_limit:
$ref: ./definitions/transfer_limit.yaml
vendor:
$ref: ./definitions/vendor.yaml
paths:
/acquisitions/baskets/managers:
$ref: paths/acquisitions_baskets.yaml#/~1acquisitions~1baskets~1managers
/acquisitions/funds:
$ref: ./paths/acquisitions_funds.yaml#/~1acquisitions~1funds
/acquisitions/funds/owners:
$ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds~1owners
/acquisitions/funds/users:
$ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds~1users
/acquisitions/orders:
$ref: ./paths/acquisitions_orders.yaml#/~1acquisitions~1orders
"/acquisitions/orders/{order_id}":
$ref: "./paths/acquisitions_orders.yaml#/~1acquisitions~1orders~1{order_id}"
/acquisitions/vendors:
$ref: ./paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors
"/acquisitions/vendors/{vendor_id}":
$ref: "./paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors~1{vendor_id}"
/advanced_editor/macros:
$ref: ./paths/advancededitormacros.yaml#/~1advanced_editor~1macros
/advanced_editor/macros/shared:
$ref: ./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared
"/advanced_editor/macros/shared/{advancededitormacro_id}":
$ref: "./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared~1{advancededitormacro_id}"
"/advanced_editor/macros/{advancededitormacro_id}":
$ref: "./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1{advancededitormacro_id}"
"/article_requests/{article_request_id}":
$ref: "./paths/article_requests.yaml#/~1article_requests~1{article_request_id}"
"/biblios/{biblio_id}":
$ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}"
"/biblios/{biblio_id}/checkouts":
$ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1checkouts"
"/biblios/{biblio_id}/items":
$ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1items"
"/biblios/{biblio_id}/pickup_locations":
$ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1pickup_locations"
"/cash_registers/{cash_register_id}/cashups":
$ref: "./paths/cash_registers.yaml#/~1cash_registers~1{cash_register_id}~1cashups"
"/cashups/{cashup_id}":
$ref: "./paths/cash_registers.yaml#/~1cashups~1{cashup_id}"
/checkouts:
$ref: ./paths/checkouts.yaml#/~1checkouts
"/checkouts/{checkout_id}":
$ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}"
"/checkouts/{checkout_id}/allows_renewal":
$ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1allows_renewal"
"/checkouts/{checkout_id}/renewal":
$ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal"
/circulation-rules/kinds:
$ref: ./paths/circulation-rules.yaml#/~1circulation-rules~1kinds
/cities:
$ref: ./paths/cities.yaml#/~1cities
"/cities/{city_id}":
$ref: "./paths/cities.yaml#/~1cities~1{city_id}"
"/clubs/{club_id}/holds":
$ref: "./paths/clubs.yaml#/~1clubs~1{club_id}~1holds"
/config/smtp_servers:
$ref: ./paths/config_smtp_servers.yaml#/~1config~1smtp_servers
"/config/smtp_servers/{smtp_server_id}":
$ref: "./paths/config_smtp_servers.yaml#/~1config~1smtp_servers~1{smtp_server_id}"
/holds:
$ref: ./paths/holds.yaml#/~1holds
"/holds/{hold_id}":
$ref: "./paths/holds.yaml#/~1holds~1{hold_id}"
"/holds/{hold_id}/pickup_location":
$ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1pickup_location"
"/holds/{hold_id}/pickup_locations":
$ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1pickup_locations"
"/holds/{hold_id}/priority":
$ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1priority"
"/holds/{hold_id}/suspension":
$ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1suspension"
/ill_backends:
$ref: ./paths/ill_backends.yaml#/~1ill_backends
"/ill_backends/{ill_backend_id}":
$ref: "./paths/ill_backends.yaml#/~1ill_backends~1{ill_backend_id}"
/illrequests:
$ref: ./paths/illrequests.yaml#/~1illrequests
"/import/{import_batch_id}/records/{import_record_id}/matches/chosen":
$ref: "./paths/import_record_matches.yaml#/~1import~1{import_batch_id}~1records~1{import_record_id}~1matches~1chosen"
/import_batch_profiles:
$ref: ./paths/import_batch_profiles.yaml#/~1import_batch_profiles
"/import_batch_profiles/{import_batch_profile_id}":
$ref: "./paths/import_batch_profiles.yaml#/~1import_batch_profiles~1{import_batch_profile_id}"
/items:
$ref: ./paths/items.yaml#/~1items
"/items/{item_id}":
$ref: "./paths/items.yaml#/~1items~1{item_id}"
"/items/{item_id}/pickup_locations":
$ref: "./paths/items.yaml#/~1items~1{item_id}~1pickup_locations"
/libraries:
$ref: ./paths/libraries.yaml#/~1libraries
"/libraries/{library_id}":
$ref: "./paths/libraries.yaml#/~1libraries~1{library_id}"
/oauth/token:
$ref: ./paths/oauth.yaml#/~1oauth~1token
/patrons:
$ref: ./paths/patrons.yaml#/~1patrons
"/patrons/{patron_id}":
$ref: "./paths/patrons.yaml#/~1patrons~1{patron_id}"
"/patrons/{patron_id}/account":
$ref: "./paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account"
"/patrons/{patron_id}/account/credits":
$ref: "./paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account~1credits"
"/patrons/{patron_id}/extended_attributes":
$ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes"
"/patrons/{patron_id}/extended_attributes/{extended_attribute_id}":
$ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id}"
"/patrons/{patron_id}/holds":
$ref: "./paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds"
"/patrons/{patron_id}/password":
$ref: "./paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password"
"/patrons/{patron_id}/password/expiration":
$ref: "./paths/patrons_password_expiration.yaml#/~1patrons~1{patron_id}~1password~1expiration"
"/public/biblios/{biblio_id}":
$ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}"
"/public/biblios/{biblio_id}/items":
$ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items"
/public/libraries:
$ref: ./paths/libraries.yaml#/~1public~1libraries
"/public/libraries/{library_id}":
$ref: "./paths/libraries.yaml#/~1public~1libraries~1{library_id}"
"/public/patrons/{patron_id}/article_requests/{article_request_id}":
$ref: "./paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id}"
"/public/patrons/{patron_id}/guarantors/can_see_charges":
$ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_charges"
"/public/patrons/{patron_id}/guarantors/can_see_checkouts":
$ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts"
"/public/patrons/{patron_id}/password":
$ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password"
/quotes:
$ref: ./paths/quotes.yaml#/~1quotes
"/quotes/{quote_id}":
$ref: "./paths/quotes.yaml#/~1quotes~1{quote_id}"
/return_claims:
$ref: ./paths/return_claims.yaml#/~1return_claims
"/return_claims/{claim_id}":
$ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}"
"/return_claims/{claim_id}/notes":
$ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1notes"
"/return_claims/{claim_id}/resolve":
$ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1resolve"
"/rotas/{rota_id}/stages/{stage_id}/position":
$ref: "./paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position"
/suggestions:
$ref: ./paths/suggestions.yaml#/~1suggestions
"/suggestions/{suggestion_id}":
$ref: "./paths/suggestions.yaml#/~1suggestions~1{suggestion_id}"
/suggestions/managers:
$ref: paths/suggestions.yaml#/~1suggestions~1managers
/transfer_limits:
$ref: ./paths/transfer_limits.yaml#/~1transfer_limits
/transfer_limits/batch:
$ref: ./paths/transfer_limits.yaml#/~1transfer_limits~1batch
"/transfer_limits/{limit_id}":
$ref: "./paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id}"
parameters:
advancededitormacro_id_pp:
description: Advanced editor macro internal identifier
in: path
name: advancededitormacro_id
required: true
type: integer
biblio_id_pp:
description: Record internal identifier
in: path
name: biblio_id
required: true
type: integer
candidate_match_id_pp:
description: Internal import record match identifier
in: path
name: candidate_match_id
required: true
type: integer
cash_register_id_pp:
description: Cash register internal identifier
in: path
name: cash_register_id
required: true
type: integer
cashup_id_pp:
description: Cashup internal identifier
in: path
name: cashup_id
required: true
type: integer
checkout_id_pp:
description: Internal checkout identifier
in: path
name: checkout_id
required: true
type: integer
city_id_pp:
description: City internal identifier
in: path
name: city_id
required: true
type: integer
club_id_pp:
description: Internal club identifier
in: path
name: club_id
required: true
type: integer
fund_id_pp:
description: Fund id
in: path
name: fund_id
required: true
type: integer
hold_id_pp:
description: Internal hold identifier
in: path
name: hold_id
required: true
type: integer
import_batch_profile_id_pp:
description: Internal profile identifier
in: path
name: import_batch_profile_id
required: true
type: integer
import_record_id_pp:
description: Internal import record identifier
in: path
name: import_record_id
required: true
type: integer
item_id_pp:
description: Internal item identifier
in: path
name: item_id
required: true
type: integer
library_id_pp:
description: Internal library identifier
in: path
name: library_id
required: true
type: string
match:
description: Matching criteria
enum:
- contains
- exact
- starts_with
- ends_with
in: query
name: _match
required: false
type: string
order_by:
collectionFormat: csv
description: Sorting criteria
in: query
items:
type: string
name: _order_by
required: false
type: array
order_id_pp:
description: Internal order identifier
in: path
name: order_id
required: true
type: integer
page:
description: "Page number, for paginated object listing"
in: query
name: _page
required: false
type: integer
patron_id_pp:
description: Internal patron identifier
in: path
name: patron_id
required: true
type: integer
patron_id_qp:
description: Internal patron identifier
in: query
name: patron_id
type: integer
per_page:
description: "Page size, for paginated object listing"
in: query
name: _per_page
required: false
type: integer
q_body:
description: Query filter sent through request"s body
in: body
name: query
required: false
schema:
type: object
q_header:
description: Query filter sent as a request header
in: header
name: x-koha-query
required: false
type: string
q_param:
description: Query filter sent as a request parameter
in: query
name: q
required: false
type: array
items:
type: string
collectionFormat: multi
quote_id_pp:
description: Quote internal identifier
in: path
name: quote_id
required: true
type: integer
request_id_header:
description: Request id header
in: header
name: x-koha-request-id
required: false
type: integer
seen_pp:
description: Item was seen flag
in: query
name: seen
required: false
type: integer
smtp_server_id_pp:
description: SMTP server internal identifier
in: path
name: smtp_server_id
required: true
type: integer
suggestion_id_pp:
description: Internal suggestion identifier
in: path
name: suggestion_id
required: true
type: integer
transfer_limit_id_pp:
description: Internal transfer limit identifier
in: path
name: limit_id
required: true
type: string
vendor_id_pp:
description: Vendor id
in: path
name: vendor_id
required: true
type: integer
info:
title: Koha REST API
version: "1"
license:
name: "GPL v3,"
url: http://www.gnu.org/licenses/gpl.txt
contact:
name: Koha Development Team
url: https://koha-community.org/
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": "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.
## 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.
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" }'`
## Special headers
### 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.
tags:
- description: "Manage article requests\n"
name: article_requests
x-displayName: Article requests
- description: "Manage bibliographic records\n"
name: biblios
x-displayName: Biblios
- description: "Manage cash register cashups\n"
name: cashups
x-displayName: Cashups
- description: "Manage checkouts\n"
name: checkouts
x-displayName: Checkouts
- description: "Manage circulation rules\n"
name: circulation_rules
x-displayName: Circulation rules
- description: "Manage cities\n"
name: cities
x-displayName: Cities
- description: "Manage patron clubs\n"
name: clubs
x-displayName: Clubs
- description: "Manage funds for the acquisitions module\n"
name: funds
x-displayName: Funds
- description: "Manage holds\n"
name: holds
x-displayName: Holds
- description: "Manage ILL module backends\n"
name: illbackends
x-displayName: ILL backends
- description: "Manage ILL requests\n"
name: illrequests
x-displayName: ILL requests
- description: "Manage items\n"
name: items
x-displayName: Items
- description: "Manage libraries\n"
name: libraries
x-displayName: Libraries
- description: "Manage macros\n"
name: macros
x-displayName: Macros
- description: "Manage acquisition orders\n"
name: orders
x-displayName: Orders
- description: "Handle OAuth flows\n"
name: oauth
x-displayName: OAuth
- description: "Manage patrons\n"
name: patrons
x-displayName: Patrons
- description: "Manage quotes\n"
name: quotes
x-displayName: Quotes
- description: "Manage return claims\n"
name: return_claims
x-displayName: Return claims
- description: "Manage rotas\n"
name: rotas
x-displayName: Rotas
- description: "Manage SMTP servers configurations\n"
name: smtp_servers
x-displayName: SMTP servers
- description: "Manage transfer limits\n"
name: transfer
x-displayName: Transfer limits
- description: "Manage purchase suggestions\n"
name: suggestions
x-displayName: Purchase suggestions
- description: "Manage vendors for the acquisitions module\n"
name: vendors
x-displayName: Vendors
- description: "Manage batch import profiles\n"
name: batch_import_profiles
x-displayName: Batch import profiles