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