Koha/api/v1/swagger/paths/holds.yaml
Jonathan Druart 7a32231a52
Bug 35353: Add REST API endpoint to retrieve old holds
Same as checkout but for holds, we need to provide a way to retrieve old
holds for a patron.

Test plan:
Create some holds for a patron, cancel and fulfill some, then use the
REST API endpoint with the new 'old' flag set to 1
  /api/v1/patrons/42/holds?old=1

Signed-off-by: Matt Blenkinsop <matt.blenkinsop@ptfs-europe.com>
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
Signed-off-by: Katrin Fischer <katrin.fischer@bsz-bw.de>
2024-04-26 18:06:09 +02:00

731 lines
21 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: item_group_id
in: query
description: Internal item group 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/request_id_header"
- name: old
in: query
description: By default, current holds are returned, when this is true then
old holds are returned as result.
type: boolean
- name: x-koha-embed
in: header
required: false
description: Embed list sent as a request header
type: array
items:
type: string
enum:
- cancellation_requested
- biblio
- pickup_library
collectionFormat: csv
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:
reserveforothers: place_holds
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"
item_group_id:
description: Internal item group 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"
- name: x-koha-override
in: header
required: false
description: Overrides list sent as a request header
type: array
items:
type: string
enum:
- cancellation-request-flow
collectionFormat: csv
produces:
- application/json
responses:
"202":
description: Hold request recorded
"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: place_holds
"/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: place_holds
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: place_holds
"/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/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. Possible `error_code` attribute values:
* `hold_waiting`
* `hold_in_transit`
* `hold_in_processing`
schema:
$ref: "../swagger.yaml#/definitions/error"
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
"503":
description: Under maintenance
schema:
$ref: "../swagger.yaml#/definitions/error"
x-koha-authorization:
permissions:
reserveforothers: place_holds