Koha/api/v1/swagger/paths/holds.yaml
Tomas Cohen Arazi b25f6f1c30 Bug 30394: Add x-koha-request-id support on API routes
This patch adds the x-koha-request-id to all GET routes that rely on
objects.search, for immediate support for the header.

The patch itself is trivial:
- It adds the header parameter definition to the top level swagger.yaml
- It adds a reference on each route that already implements q params,
  etc

To test:
1. Apply the patch
2. Reload plack
3. Notice the API still works
4. Run:
   $ kshell
  k$ prove t/db_dependent/api/v1/query.t
=> SUCCESS: It now passes! The /cities route implements the
x-koha-request-id header pass through.
5. Run the rest of the API tests
=> SUCCESS: All good
6. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>
2022-04-04 16:23:46 +02:00

679 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
description: "Comma-separated list of overrides (valid values: any)"
in: header
type: string
required: false
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
description: "Comma-separated list of overrides (valid values: any)"
in: header
type: string
required: false
- $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