Koha-community/Koha
13
7
Fork 0
Code Issues Releases Wiki Activity
Koha/api/v1/swagger/paths/holds.yaml
Tomas Cohen Arazi b7b6a85de5 Bug 28020: (follow-up) Add docs about error_code on the API 
This patch intends to be a guide for inserting Markdown documentation
for error codes. The idea is that it can be copied and pasted as-is in
new routes. And adapted to new error codes.

To test:
1. Apply this patch
2. Run:
   $ npx redoc-cli@0.10.4 bundle --cdn --output index.html \
            api/v1/swagger/swagger.yaml
=> SUCCESS: It builds correctly
3. Open index.tml on your browser
4. Pick a route, and see the 500 status description includes information
   about the possible `error_code` values.
5. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>

Signed-off-by: Andrew Fuerste-Henry <andrew@bywatersolutions.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>
2022-01-05 13:33:46 -10:00

677 lines
19 KiB
YAML
Raw Blame History

---
/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: ../parameters.yaml#/match
- $ref: ../parameters.yaml#/order_by
- $ref: ../parameters.yaml#/page
- $ref: ../parameters.yaml#/per_page
- $ref: ../parameters.yaml#/q_param
- $ref: ../parameters.yaml#/q_body
- $ref: ../parameters.yaml#/q_header
produces:
- application/json
responses:
"200":
description: A list of holds
schema:
$ref: ../definitions.yaml#/holds
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Borrower not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../definitions.yaml#/hold
"400":
description: Missing or wrong parameters
schema:
$ref: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Borrower not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../parameters.yaml#/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: ../definitions.yaml#/hold
"400":
description: Missing or wrong parameters
schema:
$ref: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../parameters.yaml#/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: ../definitions.yaml#/hold
"400":
description: Missing or wrong parameters
schema:
$ref: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
reserveforothers: "1"
delete:
x-mojo-to: Holds#delete
operationId: deleteHold
tags:
- holds
summary: Cancel hold
parameters:
- $ref: ../parameters.yaml#/hold_id_pp
produces:
- application/json
responses:
"204":
description: Hold deleted
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../parameters.yaml#/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: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Biblio not found
schema:
$ref: ../definitions.yaml#/error
"409":
description: Unable to perform action on biblio
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../parameters.yaml#/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: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
reserveforothers: "1"
delete:
x-mojo-to: Holds#resume
operationId: resumeHold
tags:
- holds
summary: Resume hold
parameters:
- $ref: ../parameters.yaml#/hold_id_pp
consumes:
- application/json
produces:
- application/json
responses:
"204":
description: Hold resumed
"400":
description: Missing or wrong parameters
schema:
$ref: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../parameters.yaml#/hold_id_pp
- $ref: ../parameters.yaml#/match
- $ref: ../parameters.yaml#/order_by
- $ref: ../parameters.yaml#/page
- $ref: ../parameters.yaml#/per_page
- $ref: ../parameters.yaml#/q_param
- $ref: ../parameters.yaml#/q_body
- $ref: ../parameters.yaml#/q_header
produces:
- application/json
responses:
"200":
description: Hold pickup location
schema:
type: array
items:
$ref: ../definitions.yaml#/library
"400":
description: Missing or wrong parameters
schema:
$ref: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Hold pickup location list not allowed
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"500":
description: |
Internal server error. Possible `error_code` attribute values:
* `internal_server_error`
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/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: ../parameters.yaml#/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: ../definitions.yaml#/error
"401":
description: Authentication required
schema:
$ref: ../definitions.yaml#/error
"403":
description: Access forbidden
schema:
$ref: ../definitions.yaml#/error
"404":
description: Hold not found
schema:
$ref: ../definitions.yaml#/error
"409":
description: Unable to perform action on hold
schema:
$ref: ../definitions.yaml#/error
"500":
description: Internal error
schema:
$ref: ../definitions.yaml#/error
"503":
description: Under maintenance
schema:
$ref: ../definitions.yaml#/error
x-koha-authorization:
permissions:
reserveforothers: place_holds
View git blame Copy permalink