Jonathan Druart
b93e15c235
Bug 28786 added the ability to turn on a two-factor authentication, using a One Time Password (OTP). Once enabled on the system, librarian had the choice to enable or disable it for themselves. For security reason an administrator could decide to force the librarians to use this second authentication step. This patch adds a third option to the existing syspref, 'Enforced', for that purpose. QA notes: the code we had in the members/two_factor_auth.pl controller has been moved to REST API controller methods (with their tests and swagger specs), for reusability reason. Code from template has been moved to an include file for the same reason. Test plan: A. Regression tests As we modified the code we need first to confirm the existing features are still working as expected. 1. Turn off TwoFactorAuthentication (disabled) and confirm that you are not able to enable and access the second authentication step 2. Turn it on (enabled) and confirm that you are able to enable it in your account 3. Logout and confirm then that you are able to login into Koha B. The new option 1. Set the pref to "enforced" 2. You are not logged out, logged in users stay logged in 3. Pick a user that does not have 2FA setup, login 4. Notice the new screen (UI is a bit ugly, suggestions welcomed) 5. Try to access Koha without enabling 2FA, you shouldn't be able to access any pages 6. Setup 2FA and confirm that you are redirected to the login screen 7. Login, send the correct pin code => You are fully logged in! Note that at 6 we could redirect to the mainpage, without the need to login again, but I think it's preferable to reduce the change to C4::Auth. If it's considered mandatory by QA I could have a look on another bug report. Sponsored-by: Rijksmuseum, Netherlands Signed-off-by: Nick Clemens <nick@bywatersolutions.com> Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
664 lines
23 KiB
YAML
664 lines
23 KiB
YAML
---
|
|
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
|
|
bundle_link:
|
|
$ref: ./definitions/bundle_link.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
|
|
item_group:
|
|
$ref: ./definitions/item_group.yaml
|
|
job:
|
|
$ref: ./definitions/job.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
|
|
renewal:
|
|
$ref: ./definitions/renewal.yaml
|
|
renewals:
|
|
$ref: ./definitions/renewals.yaml
|
|
return_claim:
|
|
$ref: ./definitions/return_claim.yaml
|
|
search_filter:
|
|
$ref: ./definitions/search_filter.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
|
|
/search_filters:
|
|
$ref: ./paths/search_filters.yaml#/~1search_filters
|
|
"/search_filters/{search_filter_id}":
|
|
$ref: "./paths/search_filters.yaml#/~1search_filters~1{search_filter_id}"
|
|
"/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}"
|
|
/auth/otp/token_delivery:
|
|
$ref: paths/auth.yaml#/~1auth~1otp~1token_delivery
|
|
/auth/two-factor/registration:
|
|
$ref: paths/auth.yaml#/~1auth~1two-factor~1registration
|
|
/auth/two-factor/registration/verification:
|
|
$ref: paths/auth.yaml#/~1auth~1two-factor~1registration~1verification
|
|
"/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"
|
|
"/biblios/{biblio_id}/item_groups":
|
|
$ref: "./paths/biblios_item_groups.yaml#/~1biblios~1{biblio_id}~1item_groups"
|
|
"/biblios/{biblio_id}/item_groups/{item_group_id}":
|
|
$ref: "./paths/biblios_item_groups.yaml#/~1biblios~1{biblio_id}~1item_groups~1{item_group_id}"
|
|
"/biblios/{biblio_id}/item_groups/{item_group_id}/items":
|
|
$ref: "./paths/biblios_item_groups.yaml#/~1biblios~1{biblio_id}~1item_groups~1{item_group_id}~1items"
|
|
"/biblios/{biblio_id}/item_groups/{item_group_id}/items/{item_id}":
|
|
$ref: "./paths/biblios_item_groups.yaml#/~1biblios~1{biblio_id}~1item_groups~1{item_group_id}~1items~1{item_id}"
|
|
"/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}/renewals":
|
|
$ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewals"
|
|
"/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_batches/{import_batch_id}/records/{import_record_id}/matches/chosen":
|
|
$ref: "./paths/import_batches.yaml#/~1import_batches~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}/bundled_items":
|
|
$ref: ./paths/items.yaml#/~1items~1{item_id}~1bundled_items
|
|
"/items/{item_id}/bundled_items/{bundled_item_id}":
|
|
$ref: ./paths/items.yaml#/~1items~1{item_id}~1bundled_items~1{bundled_item_id}
|
|
"/items/{item_id}/pickup_locations":
|
|
$ref: "./paths/items.yaml#/~1items~1{item_id}~1pickup_locations"
|
|
/jobs:
|
|
$ref: ./paths/jobs.yaml#/~1jobs
|
|
"/jobs/{job_id}":
|
|
$ref: "./paths/jobs.yaml#/~1jobs~1{job_id}"
|
|
/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_date":
|
|
$ref: "./paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password~1expiration_date"
|
|
"/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/biblios/{biblio_id}/ratings":
|
|
$ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1ratings"
|
|
/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
|
|
job_id_pp:
|
|
description: Job internal identifier
|
|
in: path
|
|
name: job_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
|
|
search_filter_id_pp:
|
|
name: search_filter_id
|
|
in: path
|
|
description: Search filter internal identifier
|
|
required: true
|
|
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: "Handle two factor authentication flows\n"
|
|
name: 2fa
|
|
x-displayName: Two factor authentication
|
|
- description: "Manage article requests\n"
|
|
name: article_requests
|
|
x-displayName: Article requests
|
|
- description: "Manage baskets for the acquisitions module\n"
|
|
name: baskets
|
|
x-displayName: Baskets
|
|
- 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 import batches\n"
|
|
name: import_batches
|
|
x-display-name: Import batches
|
|
- description: "Manage item groups\n"
|
|
name: item_groups
|
|
x-displayName: Item groups
|
|
- description: "Manage items\n"
|
|
name: items
|
|
x-displayName: Items
|
|
- description: "Manage jobs\n"
|
|
name: jobs
|
|
x-displayName: Jobs
|
|
- 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
|