api/v1/swagger/paths/holds.json

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