api/v1/swagger/paths/holds.yaml

   1 ---
   2 /holds:
   3   get:
   4     x-mojo-to: Holds#list
   5     operationId: listHolds
   6     tags:
   7       - holds
   8     summary: List holds
   9     parameters:
  10       - name: hold_id
  11         in: query
  12         description: Internal hold identifier
  13         type: integer
  14       - name: patron_id
  15         in: query
  16         description: Internal patron identifier
  17         type: integer
  18       - name: hold_date
  19         in: query
  20         description: Hold
  21         type: string
  22         format: date
  23       - name: biblio_id
  24         in: query
  25         description: Internal biblio identifier
  26         type: integer
  27       - name: pickup_library_id
  28         in: query
  29         description: Internal library identifier for the pickup library
  30         type: string
  31       - name: cancellation_date
  32         in: query
  33         description: The date the hold was cancelled
  34         type: string
  35         format: date
  36       - name: notes
  37         in: query
  38         description: Notes related to this hold
  39         type: string
  40       - name: priority
  41         in: query
  42         description: Where in the queue the patron sits
  43         type: integer
  44       - name: status
  45         in: query
  46         description: Found status
  47         type: string
  48       - name: timestamp
  49         in: query
  50         description: Time of latest update
  51         type: string
  52       - name: item_id
  53         in: query
  54         description: Internal item identifier
  55         type: integer
  56       - name: waiting_date
  57         in: query
  58         description: Date the item was marked as waiting for the patron
  59         type: string
  60       - name: expiration_date
  61         in: query
  62         description: Date the hold expires
  63         type: string
  64       - name: lowest_priority
  65         in: query
  66         description: Lowest priority
  67         type: boolean
  68       - name: suspended
  69         in: query
  70         description: Suspended
  71         type: boolean
  72       - name: suspended_until
  73         in: query
  74         description: Suspended until
  75         type: string
  76       - name: non_priority
  77         in: query
  78         description: Non priority hold
  79         type: boolean
  80       - $ref: "../swagger.yaml#/parameters/match"
  81       - $ref: "../swagger.yaml#/parameters/order_by"
  82       - $ref: "../swagger.yaml#/parameters/page"
  83       - $ref: "../swagger.yaml#/parameters/per_page"
  84       - $ref: "../swagger.yaml#/parameters/q_param"
  85       - $ref: "../swagger.yaml#/parameters/q_body"
  86       - $ref: "../swagger.yaml#/parameters/q_header"
  87       - $ref: "../swagger.yaml#/parameters/request_id_header"
  88     produces:
  89       - application/json
  90     responses:
  91       "200":
  92         description: A list of holds
  93         schema:
  94           $ref: "../swagger.yaml#/definitions/holds"
  95       "401":
  96         description: Authentication required
  97         schema:
  98           $ref: "../swagger.yaml#/definitions/error"
  99       "403":
 100         description: Hold not allowed
 101         schema:
 102           $ref: "../swagger.yaml#/definitions/error"
 103       "404":
 104         description: Borrower not found
 105         schema:
 106           $ref: "../swagger.yaml#/definitions/error"
 107       "500":
 108         description: |
 109           Internal server error. Possible `error_code` attribute values:
 110
 111           * `internal_server_error`
 112         schema:
 113           $ref: "../swagger.yaml#/definitions/error"
 114       "503":
 115         description: Under maintenance
 116         schema:
 117           $ref: "../swagger.yaml#/definitions/error"
 118     x-koha-authorization:
 119       permissions:
 120         borrowers: edit_borrowers
 121   post:
 122     x-mojo-to: Holds#add
 123     operationId: addHold
 124     tags:
 125       - holds
 126     summary: Place hold
 127     parameters:
 128       - name: body
 129         in: body
 130         description: A JSON object containing informations about the new hold
 131         required: true
 132         schema:
 133           type: object
 134           properties:
 135             patron_id:
 136               description: Internal patron identifier
 137               type: integer
 138             biblio_id:
 139               description: Internal biblio identifier
 140               type:
 141                 - integer
 142                 - "null"
 143             hold_date:
 144               description: The date the hold was placed
 145               type:
 146                 - string
 147                 - "null"
 148               format: date
 149             item_id:
 150               description: Internal item identifier
 151               type:
 152                 - integer
 153                 - "null"
 154             pickup_library_id:
 155               description: Internal library identifier for the pickup library
 156               type: string
 157             expiration_date:
 158               description: Hold end date
 159               type:
 160                 - string
 161                 - "null"
 162               format: date
 163             notes:
 164               description: Notes related to this hold
 165               type:
 166                 - string
 167                 - "null"
 168             item_type:
 169               description: Limit hold on one itemtype (ignored for item-level holds)
 170               type:
 171                 - string
 172                 - "null"
 173             non_priority:
 174               description: Set this hold as non priority
 175               type:
 176                 - boolean
 177                 - "null"
 178           required:
 179             - patron_id
 180             - pickup_library_id
 181           additionalProperties: false
 182       - name: x-koha-override
 183         in: header
 184         required: false
 185         description: Overrides list sent as a request header
 186         type: array
 187         items:
 188           type: string
 189           enum:
 190             - any
 191         collectionFormat: csv
 192     consumes:
 193       - application/json
 194     produces:
 195       - application/json
 196     responses:
 197       "201":
 198         description: Created hold
 199         schema:
 200           $ref: "../swagger.yaml#/definitions/hold"
 201       "400":
 202         description: Missing or wrong parameters
 203         schema:
 204           $ref: "../swagger.yaml#/definitions/error"
 205       "401":
 206         description: Authentication required
 207         schema:
 208           $ref: "../swagger.yaml#/definitions/error"
 209       "403":
 210         description: Hold not allowed
 211         schema:
 212           $ref: "../swagger.yaml#/definitions/error"
 213       "404":
 214         description: Borrower not found
 215         schema:
 216           $ref: "../swagger.yaml#/definitions/error"
 217       "500":
 218         description: |
 219           Internal server error. Possible `error_code` attribute values:
 220
 221           * `internal_server_error`
 222         schema:
 223           $ref: "../swagger.yaml#/definitions/error"
 224       "503":
 225         description: Under maintenance
 226         schema:
 227           $ref: "../swagger.yaml#/definitions/error"
 228     x-koha-authorization:
 229       permissions:
 230         reserveforothers: "1"
 231 "/holds/{hold_id}":
 232   patch:
 233     x-mojo-to: Holds#edit
 234     operationId: editHold
 235     tags:
 236       - holds
 237     summary: Update hold
 238     parameters:
 239       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 240       - name: body
 241         in: body
 242         description: A JSON object containing fields to modify
 243         required: true
 244         schema:
 245           type: object
 246           properties:
 247             priority:
 248               description: Position in waiting queue
 249               type: integer
 250               minimum: 1
 251             pickup_library_id:
 252               description: Internal library identifier for the pickup library
 253               type: string
 254             suspended_until:
 255               description: Date until which the hold has been suspended
 256               type: string
 257               format: date-time
 258           additionalProperties: false
 259     consumes:
 260       - application/json
 261     produces:
 262       - application/json
 263     responses:
 264       "200":
 265         description: Updated hold
 266         schema:
 267           $ref: "../swagger.yaml#/definitions/hold"
 268       "400":
 269         description: Missing or wrong parameters
 270         schema:
 271           $ref: "../swagger.yaml#/definitions/error"
 272       "401":
 273         description: Authentication required
 274         schema:
 275           $ref: "../swagger.yaml#/definitions/error"
 276       "403":
 277         description: Hold not allowed
 278         schema:
 279           $ref: "../swagger.yaml#/definitions/error"
 280       "404":
 281         description: Hold not found
 282         schema:
 283           $ref: "../swagger.yaml#/definitions/error"
 284       "500":
 285         description: |
 286           Internal server error. Possible `error_code` attribute values:
 287
 288           * `internal_server_error`
 289         schema:
 290           $ref: "../swagger.yaml#/definitions/error"
 291       "503":
 292         description: Under maintenance
 293         schema:
 294           $ref: "../swagger.yaml#/definitions/error"
 295     x-koha-authorization:
 296       permissions:
 297         reserveforothers: "1"
 298   put:
 299     x-mojo-to: Holds#edit
 300     operationId: overwriteHold
 301     tags:
 302       - holds
 303     summary: Update hold
 304     description: This route is being deprecated and will be removed in future releases.
 305       Please migrate your project to use PATCH /holds/{hold_id} instead.
 306     parameters:
 307       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 308       - name: body
 309         in: body
 310         description: A JSON object containing fields to modify
 311         required: true
 312         schema:
 313           type: object
 314           properties:
 315             priority:
 316               description: Position in waiting queue
 317               type: integer
 318               minimum: 1
 319             pickup_library_id:
 320               description: Internal library identifier for the pickup library
 321               type: string
 322             suspended_until:
 323               description: Date until which the hold has been suspended
 324               type: string
 325               format: date-time
 326           additionalProperties: false
 327     consumes:
 328       - application/json
 329     produces:
 330       - application/json
 331     responses:
 332       "200":
 333         description: Updated hold
 334         schema:
 335           $ref: "../swagger.yaml#/definitions/hold"
 336       "400":
 337         description: Missing or wrong parameters
 338         schema:
 339           $ref: "../swagger.yaml#/definitions/error"
 340       "401":
 341         description: Authentication required
 342         schema:
 343           $ref: "../swagger.yaml#/definitions/error"
 344       "403":
 345         description: Hold not allowed
 346         schema:
 347           $ref: "../swagger.yaml#/definitions/error"
 348       "404":
 349         description: Hold not found
 350         schema:
 351           $ref: "../swagger.yaml#/definitions/error"
 352       "500":
 353         description: |
 354           Internal server error. Possible `error_code` attribute values:
 355
 356           * `internal_server_error`
 357         schema:
 358           $ref: "../swagger.yaml#/definitions/error"
 359       "503":
 360         description: Under maintenance
 361         schema:
 362           $ref: "../swagger.yaml#/definitions/error"
 363     x-koha-authorization:
 364       permissions:
 365         reserveforothers: "1"
 366   delete:
 367     x-mojo-to: Holds#delete
 368     operationId: deleteHold
 369     tags:
 370       - holds
 371     summary: Cancel hold
 372     parameters:
 373       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 374     produces:
 375       - application/json
 376     responses:
 377       "204":
 378         description: Hold deleted
 379       "401":
 380         description: Authentication required
 381         schema:
 382           $ref: "../swagger.yaml#/definitions/error"
 383       "403":
 384         description: Hold not allowed
 385         schema:
 386           $ref: "../swagger.yaml#/definitions/error"
 387       "404":
 388         description: Hold not found
 389         schema:
 390           $ref: "../swagger.yaml#/definitions/error"
 391       "500":
 392         description: |
 393           Internal server error. Possible `error_code` attribute values:
 394
 395           * `internal_server_error`
 396         schema:
 397           $ref: "../swagger.yaml#/definitions/error"
 398       "503":
 399         description: Under maintenance
 400         schema:
 401           $ref: "../swagger.yaml#/definitions/error"
 402     x-koha-authorization:
 403       permissions:
 404         reserveforothers: place_holds
 405 "/holds/{hold_id}/priority":
 406   put:
 407     x-mojo-to: Holds#update_priority
 408     operationId: updateHoldPriority
 409     tags:
 410       - holds
 411     summary: Update priority for the hold
 412     parameters:
 413       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 414       - name: body
 415         in: body
 416         description: An integer representing the new priority to be set for the hold
 417         required: true
 418         schema:
 419           type: integer
 420     produces:
 421       - application/json
 422     responses:
 423       "200":
 424         description: The new priority value for the hold
 425         schema:
 426           type: integer
 427       "401":
 428         description: Authentication required
 429         schema:
 430           $ref: "../swagger.yaml#/definitions/error"
 431       "403":
 432         description: Access forbidden
 433         schema:
 434           $ref: "../swagger.yaml#/definitions/error"
 435       "404":
 436         description: Biblio not found
 437         schema:
 438           $ref: "../swagger.yaml#/definitions/error"
 439       "409":
 440         description: Unable to perform action on biblio
 441         schema:
 442           $ref: "../swagger.yaml#/definitions/error"
 443       "500":
 444         description: |
 445           Internal server error. Possible `error_code` attribute values:
 446
 447           * `internal_server_error`
 448         schema:
 449           $ref: "../swagger.yaml#/definitions/error"
 450       "503":
 451         description: Under maintenance
 452         schema:
 453           $ref: "../swagger.yaml#/definitions/error"
 454     x-koha-authorization:
 455       permissions:
 456         reserveforothers: modify_holds_priority
 457 "/holds/{hold_id}/suspension":
 458   post:
 459     x-mojo-to: Holds#suspend
 460     operationId: suspendHold
 461     tags:
 462       - holds
 463     summary: Suspend the hold
 464     parameters:
 465       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 466       - name: body
 467         in: body
 468         description: A JSON object containing fields to modify
 469         required: false
 470         schema:
 471           type: object
 472           properties:
 473             end_date:
 474               description: Date the hold suspension expires
 475               type: string
 476               format: date
 477           additionalProperties: false
 478     consumes:
 479       - application/json
 480     produces:
 481       - application/json
 482     responses:
 483       "201":
 484         description: Hold suspended
 485       "400":
 486         description: Missing or wrong parameters
 487         schema:
 488           $ref: "../swagger.yaml#/definitions/error"
 489       "401":
 490         description: Authentication required
 491         schema:
 492           $ref: "../swagger.yaml#/definitions/error"
 493       "403":
 494         description: Hold not allowed
 495         schema:
 496           $ref: "../swagger.yaml#/definitions/error"
 497       "404":
 498         description: Hold not found
 499         schema:
 500           $ref: "../swagger.yaml#/definitions/error"
 501       "500":
 502         description: |
 503           Internal server error. Possible `error_code` attribute values:
 504
 505           * `internal_server_error`
 506         schema:
 507           $ref: "../swagger.yaml#/definitions/error"
 508       "503":
 509         description: Under maintenance
 510         schema:
 511           $ref: "../swagger.yaml#/definitions/error"
 512     x-koha-authorization:
 513       permissions:
 514         reserveforothers: place_holds
 515   delete:
 516     x-mojo-to: Holds#resume
 517     operationId: resumeHold
 518     tags:
 519       - holds
 520     summary: Resume hold
 521     parameters:
 522       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 523     consumes:
 524       - application/json
 525     produces:
 526       - application/json
 527     responses:
 528       "204":
 529         description: Hold resumed
 530       "400":
 531         description: Missing or wrong parameters
 532         schema:
 533           $ref: "../swagger.yaml#/definitions/error"
 534       "401":
 535         description: Authentication required
 536         schema:
 537           $ref: "../swagger.yaml#/definitions/error"
 538       "403":
 539         description: Hold not allowed
 540         schema:
 541           $ref: "../swagger.yaml#/definitions/error"
 542       "404":
 543         description: Hold not found
 544         schema:
 545           $ref: "../swagger.yaml#/definitions/error"
 546       "500":
 547         description: |
 548           Internal server error. Possible `error_code` attribute values:
 549
 550           * `internal_server_error`
 551         schema:
 552           $ref: "../swagger.yaml#/definitions/error"
 553       "503":
 554         description: Under maintenance
 555         schema:
 556           $ref: "../swagger.yaml#/definitions/error"
 557     x-koha-authorization:
 558       permissions:
 559         reserveforothers: place_holds
 560 "/holds/{hold_id}/pickup_locations":
 561   get:
 562     x-mojo-to: Holds#pickup_locations
 563     operationId: getHoldPickupLocations
 564     tags:
 565       - holds
 566     summary: Get valid pickup locations for hold
 567     parameters:
 568       - name: x-koha-override
 569         in: header
 570         required: false
 571         description: Overrides list sent as a request header
 572         type: array
 573         items:
 574           type: string
 575           enum:
 576             - any
 577         collectionFormat: csv
 578       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 579       - $ref: "../swagger.yaml#/parameters/match"
 580       - $ref: "../swagger.yaml#/parameters/order_by"
 581       - $ref: "../swagger.yaml#/parameters/page"
 582       - $ref: "../swagger.yaml#/parameters/per_page"
 583       - $ref: "../swagger.yaml#/parameters/q_param"
 584       - $ref: "../swagger.yaml#/parameters/q_body"
 585       - $ref: "../swagger.yaml#/parameters/q_header"
 586       - $ref: "../swagger.yaml#/parameters/request_id_header"
 587     produces:
 588       - application/json
 589     responses:
 590       "200":
 591         description: Hold pickup location
 592         schema:
 593           type: array
 594           items:
 595             $ref: "../swagger.yaml#/definitions/library"
 596       "400":
 597         description: Missing or wrong parameters
 598         schema:
 599           $ref: "../swagger.yaml#/definitions/error"
 600       "401":
 601         description: Authentication required
 602         schema:
 603           $ref: "../swagger.yaml#/definitions/error"
 604       "403":
 605         description: Hold pickup location list not allowed
 606         schema:
 607           $ref: "../swagger.yaml#/definitions/error"
 608       "404":
 609         description: Hold not found
 610         schema:
 611           $ref: "../swagger.yaml#/definitions/error"
 612       "500":
 613         description: |
 614           Internal server error. Possible `error_code` attribute values:
 615
 616           * `internal_server_error`
 617         schema:
 618           $ref: "../swagger.yaml#/definitions/error"
 619       "503":
 620         description: Under maintenance
 621         schema:
 622           $ref: "../swagger.yaml#/definitions/error"
 623     x-koha-authorization:
 624       permissions:
 625         reserveforothers: place_holds
 626 "/holds/{hold_id}/pickup_location":
 627   put:
 628     x-mojo-to: Holds#update_pickup_location
 629     operationId: updateHoldPickupLocation
 630     tags:
 631       - holds
 632     summary: Update pickup location for the hold
 633     description: Set a new pickup location for the hold
 634     parameters:
 635       - $ref: "../swagger.yaml#/parameters/hold_id_pp"
 636       - name: body
 637         in: body
 638         description: Pickup location
 639         required: true
 640         schema:
 641           type: object
 642           properties:
 643             pickup_library_id:
 644               type: string
 645               description: Internal identifier for the pickup library
 646           additionalProperties: false
 647     produces:
 648       - application/json
 649     responses:
 650       "200":
 651         description: The new pickup location value for the hold
 652         schema:
 653           type: object
 654           properties:
 655             pickup_library_id:
 656               type: string
 657               description: Internal identifier for the pickup library
 658           additionalProperties: false
 659       "400":
 660         description: Missing or wrong parameters
 661         schema:
 662           $ref: "../swagger.yaml#/definitions/error"
 663       "401":
 664         description: Authentication required
 665         schema:
 666           $ref: "../swagger.yaml#/definitions/error"
 667       "403":
 668         description: Access forbidden
 669         schema:
 670           $ref: "../swagger.yaml#/definitions/error"
 671       "404":
 672         description: Hold not found
 673         schema:
 674           $ref: "../swagger.yaml#/definitions/error"
 675       "409":
 676         description: Unable to perform action on hold
 677         schema:
 678           $ref: "../swagger.yaml#/definitions/error"
 679       "500":
 680         description: Internal error
 681         schema:
 682           $ref: "../swagger.yaml#/definitions/error"
 683       "503":
 684         description: Under maintenance
 685         schema:
 686           $ref: "../swagger.yaml#/definitions/error"
 687     x-koha-authorization:
 688       permissions:
 689         reserveforothers: place_holds