Tomas Cohen Arazi
63d324db28
This patch makes this header parameter rely on the OpenAPI spec to
validate and document the available options.
Right now the only place is in POST and PUT /holds.
To test:
1. Run:
$ kshell
k$ prove t/db_dependent/api/v1/holds.t \
t/db_dependent/api/v1/auth_authenticate_api_request.t
=> SUCCESS: Tests pass
2. Apply this patch
3. Repeat 1
=> SUCCESS: Tests still pass!
4. Sign off :-D
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: David Nind <david@davidnind.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
689 lines
20 KiB
YAML
689 lines
20 KiB
YAML
---
|
|
/holds:
|
|
get:
|
|
x-mojo-to: Holds#list
|
|
operationId: listHolds
|
|
tags:
|
|
- holds
|
|
summary: List holds
|
|
parameters:
|
|
- name: hold_id
|
|
in: query
|
|
description: Internal hold identifier
|
|
type: integer
|
|
- name: patron_id
|
|
in: query
|
|
description: Internal patron identifier
|
|
type: integer
|
|
- name: hold_date
|
|
in: query
|
|
description: Hold
|
|
type: string
|
|
format: date
|
|
- name: biblio_id
|
|
in: query
|
|
description: Internal biblio identifier
|
|
type: integer
|
|
- name: pickup_library_id
|
|
in: query
|
|
description: Internal library identifier for the pickup library
|
|
type: string
|
|
- name: cancellation_date
|
|
in: query
|
|
description: The date the hold was cancelled
|
|
type: string
|
|
format: date
|
|
- name: notes
|
|
in: query
|
|
description: Notes related to this hold
|
|
type: string
|
|
- name: priority
|
|
in: query
|
|
description: Where in the queue the patron sits
|
|
type: integer
|
|
- name: status
|
|
in: query
|
|
description: Found status
|
|
type: string
|
|
- name: timestamp
|
|
in: query
|
|
description: Time of latest update
|
|
type: string
|
|
- name: item_id
|
|
in: query
|
|
description: Internal item identifier
|
|
type: integer
|
|
- name: waiting_date
|
|
in: query
|
|
description: Date the item was marked as waiting for the patron
|
|
type: string
|
|
- name: expiration_date
|
|
in: query
|
|
description: Date the hold expires
|
|
type: string
|
|
- name: lowest_priority
|
|
in: query
|
|
description: Lowest priority
|
|
type: boolean
|
|
- name: suspended
|
|
in: query
|
|
description: Suspended
|
|
type: boolean
|
|
- name: suspended_until
|
|
in: query
|
|
description: Suspended until
|
|
type: string
|
|
- name: non_priority
|
|
in: query
|
|
description: Non priority hold
|
|
type: boolean
|
|
- $ref: "../swagger.yaml#/parameters/match"
|
|
- $ref: "../swagger.yaml#/parameters/order_by"
|
|
- $ref: "../swagger.yaml#/parameters/page"
|
|
- $ref: "../swagger.yaml#/parameters/per_page"
|
|
- $ref: "../swagger.yaml#/parameters/q_param"
|
|
- $ref: "../swagger.yaml#/parameters/q_body"
|
|
- $ref: "../swagger.yaml#/parameters/q_header"
|
|
- $ref: "../swagger.yaml#/parameters/request_id_header"
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: A list of holds
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/holds"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Borrower not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
borrowers: edit_borrowers
|
|
post:
|
|
x-mojo-to: Holds#add
|
|
operationId: addHold
|
|
tags:
|
|
- holds
|
|
summary: Place hold
|
|
parameters:
|
|
- name: body
|
|
in: body
|
|
description: A JSON object containing informations about the new hold
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
patron_id:
|
|
description: Internal patron identifier
|
|
type: integer
|
|
biblio_id:
|
|
description: Internal biblio identifier
|
|
type:
|
|
- integer
|
|
- "null"
|
|
hold_date:
|
|
description: The date the hold was placed
|
|
type:
|
|
- string
|
|
- "null"
|
|
format: date
|
|
item_id:
|
|
description: Internal item identifier
|
|
type:
|
|
- integer
|
|
- "null"
|
|
pickup_library_id:
|
|
description: Internal library identifier for the pickup library
|
|
type: string
|
|
expiration_date:
|
|
description: Hold end date
|
|
type:
|
|
- string
|
|
- "null"
|
|
format: date
|
|
notes:
|
|
description: Notes related to this hold
|
|
type:
|
|
- string
|
|
- "null"
|
|
item_type:
|
|
description: Limit hold on one itemtype (ignored for item-level holds)
|
|
type:
|
|
- string
|
|
- "null"
|
|
non_priority:
|
|
description: Set this hold as non priority
|
|
type:
|
|
- boolean
|
|
- "null"
|
|
required:
|
|
- patron_id
|
|
- pickup_library_id
|
|
additionalProperties: false
|
|
- name: x-koha-override
|
|
in: header
|
|
required: false
|
|
description: Overrides list sent as a request header
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- any
|
|
collectionFormat: csv
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created hold
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/hold"
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Borrower not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: "1"
|
|
"/holds/{hold_id}":
|
|
patch:
|
|
x-mojo-to: Holds#edit
|
|
operationId: editHold
|
|
tags:
|
|
- holds
|
|
summary: Update hold
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
- name: body
|
|
in: body
|
|
description: A JSON object containing fields to modify
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
priority:
|
|
description: Position in waiting queue
|
|
type: integer
|
|
minimum: 1
|
|
pickup_library_id:
|
|
description: Internal library identifier for the pickup library
|
|
type: string
|
|
suspended_until:
|
|
description: Date until which the hold has been suspended
|
|
type: string
|
|
format: date-time
|
|
additionalProperties: false
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Updated hold
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/hold"
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: "1"
|
|
put:
|
|
x-mojo-to: Holds#edit
|
|
operationId: overwriteHold
|
|
tags:
|
|
- holds
|
|
summary: Update hold
|
|
description: This route is being deprecated and will be removed in future releases.
|
|
Please migrate your project to use PATCH /holds/{hold_id} instead.
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
- name: body
|
|
in: body
|
|
description: A JSON object containing fields to modify
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
priority:
|
|
description: Position in waiting queue
|
|
type: integer
|
|
minimum: 1
|
|
pickup_library_id:
|
|
description: Internal library identifier for the pickup library
|
|
type: string
|
|
suspended_until:
|
|
description: Date until which the hold has been suspended
|
|
type: string
|
|
format: date-time
|
|
additionalProperties: false
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Updated hold
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/hold"
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: "1"
|
|
delete:
|
|
x-mojo-to: Holds#delete
|
|
operationId: deleteHold
|
|
tags:
|
|
- holds
|
|
summary: Cancel hold
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"204":
|
|
description: Hold deleted
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: "1"
|
|
"/holds/{hold_id}/priority":
|
|
put:
|
|
x-mojo-to: Holds#update_priority
|
|
operationId: updateHoldPriority
|
|
tags:
|
|
- holds
|
|
summary: Update priority for the hold
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
- name: body
|
|
in: body
|
|
description: An integer representing the new priority to be set for the hold
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: The new priority value for the hold
|
|
schema:
|
|
type: integer
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Biblio not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"409":
|
|
description: Unable to perform action on biblio
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: modify_holds_priority
|
|
"/holds/{hold_id}/suspension":
|
|
post:
|
|
x-mojo-to: Holds#suspend
|
|
operationId: suspendHold
|
|
tags:
|
|
- holds
|
|
summary: Suspend the hold
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
- name: body
|
|
in: body
|
|
description: A JSON object containing fields to modify
|
|
required: false
|
|
schema:
|
|
type: object
|
|
properties:
|
|
end_date:
|
|
description: Date the hold suspension expires
|
|
type: string
|
|
format: date
|
|
additionalProperties: false
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Hold suspended
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: "1"
|
|
delete:
|
|
x-mojo-to: Holds#resume
|
|
operationId: resumeHold
|
|
tags:
|
|
- holds
|
|
summary: Resume hold
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"204":
|
|
description: Hold resumed
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: "1"
|
|
"/holds/{hold_id}/pickup_locations":
|
|
get:
|
|
x-mojo-to: Holds#pickup_locations
|
|
operationId: getHoldPickupLocations
|
|
tags:
|
|
- holds
|
|
summary: Get valid pickup locations for hold
|
|
parameters:
|
|
- name: x-koha-override
|
|
in: header
|
|
required: false
|
|
description: Overrides list sent as a request header
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- any
|
|
collectionFormat: csv
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
- $ref: "../swagger.yaml#/parameters/match"
|
|
- $ref: "../swagger.yaml#/parameters/order_by"
|
|
- $ref: "../swagger.yaml#/parameters/page"
|
|
- $ref: "../swagger.yaml#/parameters/per_page"
|
|
- $ref: "../swagger.yaml#/parameters/q_param"
|
|
- $ref: "../swagger.yaml#/parameters/q_body"
|
|
- $ref: "../swagger.yaml#/parameters/q_header"
|
|
- $ref: "../swagger.yaml#/parameters/request_id_header"
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Hold pickup location
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "../swagger.yaml#/definitions/library"
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Hold pickup location list not allowed
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: |
|
|
Internal server error. Possible `error_code` attribute values:
|
|
|
|
* `internal_server_error`
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: place_holds
|
|
"/holds/{hold_id}/pickup_location":
|
|
put:
|
|
x-mojo-to: Holds#update_pickup_location
|
|
operationId: updateHoldPickupLocation
|
|
tags:
|
|
- holds
|
|
summary: Update pickup location for the hold
|
|
description: Set a new pickup location for the hold
|
|
parameters:
|
|
- $ref: "../swagger.yaml#/parameters/hold_id_pp"
|
|
- name: body
|
|
in: body
|
|
description: Pickup location
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pickup_library_id:
|
|
type: string
|
|
description: Internal identifier for the pickup library
|
|
additionalProperties: false
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: The new pickup location value for the hold
|
|
schema:
|
|
type: object
|
|
properties:
|
|
pickup_library_id:
|
|
type: string
|
|
description: Internal identifier for the pickup library
|
|
additionalProperties: false
|
|
"400":
|
|
description: Missing or wrong parameters
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"401":
|
|
description: Authentication required
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"403":
|
|
description: Access forbidden
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"404":
|
|
description: Hold not found
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"409":
|
|
description: Unable to perform action on hold
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"500":
|
|
description: Internal error
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
"503":
|
|
description: Under maintenance
|
|
schema:
|
|
$ref: "../swagger.yaml#/definitions/error"
|
|
x-koha-authorization:
|
|
permissions:
|
|
reserveforothers: place_holds
|