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