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             "additionalProperties": false
 219           }
 220         },
 221         {
 222           "name": "x-koha-override",
 223           "description": "Comma-separated list of overrides (valid values: any)",
 224           "in": "header",
 225           "type": "string",
 226           "required": false
 227         }
 228       ],
 229       "consumes": ["application/json"],
 230       "produces": ["application/json"],
 231       "responses": {
 232         "201": {
 233           "description": "Created hold",
 234           "schema": {
 235             "$ref": "../definitions.json#/hold"
 236           }
 237         },
 238         "400": {
 239           "description": "Missing or wrong parameters",
 240           "schema": {
 241             "$ref": "../definitions.json#/error"
 242           }
 243         },
 244         "401": {
 245           "description": "Authentication required",
 246           "schema": {
 247             "$ref": "../definitions.json#/error"
 248           }
 249         },
 250         "403": {
 251           "description": "Hold not allowed",
 252           "schema": {
 253             "$ref": "../definitions.json#/error"
 254           }
 255         },
 256         "404": {
 257           "description": "Borrower not found",
 258           "schema": {
 259             "$ref": "../definitions.json#/error"
 260           }
 261         },
 262         "500": {
 263           "description": "Internal server error",
 264           "schema": {
 265             "$ref": "../definitions.json#/error"
 266           }
 267         },
 268         "503": {
 269           "description": "Under maintenance",
 270           "schema": {
 271             "$ref": "../definitions.json#/error"
 272           }
 273         }
 274       },
 275       "x-koha-authorization": {
 276         "permissions": {
 277           "reserveforothers": "1"
 278         }
 279       }
 280     }
 281   },
 282   "/holds/{hold_id}": {
 283     "put": {
 284       "x-mojo-to": "Holds#edit",
 285       "operationId": "editHold",
 286       "tags": ["holds"],
 287       "parameters": [{
 288           "$ref": "../parameters.json#/hold_id_pp"
 289         }, {
 290           "name": "body",
 291           "in": "body",
 292           "description": "A JSON object containing fields to modify",
 293           "required": true,
 294           "schema": {
 295             "type": "object",
 296             "properties": {
 297               "priority": {
 298                 "description": "Position in waiting queue",
 299                 "type": "integer",
 300                 "minimum": 1
 301               },
 302               "branchcode": {
 303                 "description": "Pickup location",
 304                 "type": "string"
 305               },
 306               "suspend_until": {
 307                 "description": "Suspend until",
 308                 "type": "string",
 309                 "format": "date"
 310               }
 311             },
 312             "additionalProperties": false
 313           }
 314         }
 315       ],
 316       "consumes": ["application/json"],
 317       "produces": ["application/json"],
 318       "responses": {
 319         "200": {
 320           "description": "Updated hold",
 321           "schema": {
 322             "$ref": "../definitions.json#/hold"
 323           }
 324         },
 325         "400": {
 326           "description": "Missing or wrong parameters",
 327           "schema": {
 328             "$ref": "../definitions.json#/error"
 329           }
 330         },
 331         "401": {
 332           "description": "Authentication required",
 333           "schema": {
 334             "$ref": "../definitions.json#/error"
 335           }
 336         },
 337         "403": {
 338           "description": "Hold not allowed",
 339           "schema": {
 340             "$ref": "../definitions.json#/error"
 341           }
 342         },
 343         "404": {
 344           "description": "Hold not found",
 345           "schema": {
 346             "$ref": "../definitions.json#/error"
 347           }
 348         },
 349         "500": {
 350           "description": "Internal server error",
 351           "schema": {
 352             "$ref": "../definitions.json#/error"
 353           }
 354         },
 355         "503": {
 356           "description": "Under maintenance",
 357           "schema": {
 358             "$ref": "../definitions.json#/error"
 359           }
 360         }
 361       },
 362       "x-koha-authorization": {
 363         "permissions": {
 364           "reserveforothers": "1"
 365         }
 366       }
 367     },
 368     "delete": {
 369       "x-mojo-to": "Holds#delete",
 370       "operationId": "deleteHold",
 371       "tags": ["holds"],
 372       "parameters": [{
 373           "$ref": "../parameters.json#/hold_id_pp"
 374         }
 375       ],
 376       "produces": ["application/json"],
 377       "responses": {
 378         "204": {
 379           "description": "Hold deleted"
 380         },
 381         "401": {
 382           "description": "Authentication required",
 383           "schema": {
 384             "$ref": "../definitions.json#/error"
 385           }
 386         },
 387         "403": {
 388           "description": "Hold not allowed",
 389           "schema": {
 390             "$ref": "../definitions.json#/error"
 391           }
 392         },
 393         "404": {
 394           "description": "Hold not found",
 395           "schema": {
 396             "$ref": "../definitions.json#/error"
 397           }
 398         },
 399         "500": {
 400           "description": "Internal server error",
 401           "schema": {
 402             "$ref": "../definitions.json#/error"
 403           }
 404         },
 405         "503": {
 406           "description": "Under maintenance",
 407           "schema": {
 408             "$ref": "../definitions.json#/error"
 409           }
 410         }
 411       },
 412       "x-koha-authorization": {
 413         "permissions": {
 414           "reserveforothers": "1"
 415         }
 416       }
 417     }
 418   },
 419   "/holds/{hold_id}/priority": {
 420     "put": {
 421       "x-mojo-to": "Holds#update_priority",
 422       "operationId": "updateHoldPriority",
 423       "tags": [
 424         "biblios",
 425         "holds"
 426       ],
 427       "parameters": [
 428         {
 429           "$ref": "../parameters.json#/hold_id_pp"
 430         },
 431         {
 432           "name": "body",
 433           "in": "body",
 434           "description": "An integer representing the new priority to be set for the hold",
 435           "required": true,
 436           "schema": {
 437             "type": "integer"
 438           }
 439         }
 440       ],
 441       "produces": [
 442         "application/json"
 443       ],
 444       "responses": {
 445         "200": {
 446           "description": "The new priority value for the hold",
 447           "schema": {
 448             "type": "integer"
 449           }
 450         },
 451         "401": {
 452           "description": "Authentication required",
 453           "schema": {
 454             "$ref": "../definitions.json#/error"
 455           }
 456         },
 457         "403": {
 458           "description": "Access forbidden",
 459           "schema": {
 460             "$ref": "../definitions.json#/error"
 461           }
 462         },
 463         "404": {
 464           "description": "Biblio not found",
 465           "schema": {
 466             "$ref": "../definitions.json#/error"
 467           }
 468         },
 469         "409": {
 470           "description": "Unable to perform action on biblio",
 471           "schema": {
 472             "$ref": "../definitions.json#/error"
 473           }
 474         },
 475         "500": {
 476           "description": "Internal error",
 477           "schema": {
 478             "$ref": "../definitions.json#/error"
 479           }
 480         },
 481         "503": {
 482           "description": "Under maintenance",
 483           "schema": {
 484             "$ref": "../definitions.json#/error"
 485           }
 486         }
 487       },
 488       "x-koha-authorization": {
 489         "permissions": {
 490           "reserveforothers": "modify_holds_priority"
 491         }
 492       }
 493     }
 494   },
 495   "/holds/{hold_id}/suspension": {
 496     "post": {
 497       "x-mojo-to": "Holds#suspend",
 498       "operationId": "suspendHold",
 499       "tags": ["holds"],
 500       "parameters": [{
 501           "$ref": "../parameters.json#/hold_id_pp"
 502         }, {
 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               }
 515             },
 516             "additionalProperties": false
 517           }
 518         }
 519       ],
 520       "consumes": ["application/json"],
 521       "produces": ["application/json"],
 522       "responses": {
 523         "201": {
 524           "description": "Hold suspended"
 525         },
 526         "400": {
 527           "description": "Missing or wrong parameters",
 528           "schema": {
 529             "$ref": "../definitions.json#/error"
 530           }
 531         },
 532         "401": {
 533           "description": "Authentication required",
 534           "schema": {
 535             "$ref": "../definitions.json#/error"
 536           }
 537         },
 538         "403": {
 539           "description": "Hold not allowed",
 540           "schema": {
 541             "$ref": "../definitions.json#/error"
 542           }
 543         },
 544         "404": {
 545           "description": "Hold not found",
 546           "schema": {
 547             "$ref": "../definitions.json#/error"
 548           }
 549         },
 550         "500": {
 551           "description": "Internal server error",
 552           "schema": {
 553             "$ref": "../definitions.json#/error"
 554           }
 555         },
 556         "503": {
 557           "description": "Under maintenance",
 558           "schema": {
 559             "$ref": "../definitions.json#/error"
 560           }
 561         }
 562       },
 563       "x-koha-authorization": {
 564         "permissions": {
 565           "reserveforothers": "1"
 566         }
 567       }
 568     },
 569     "delete": {
 570       "x-mojo-to": "Holds#resume",
 571       "operationId": "resumeHold",
 572       "tags": ["holds"],
 573       "parameters": [
 574         {
 575           "$ref": "../parameters.json#/hold_id_pp"
 576         }
 577       ],
 578       "consumes": ["application/json"],
 579       "produces": ["application/json"],
 580       "responses": {
 581         "204": {
 582           "description": "Hold resumed"
 583         },
 584         "400": {
 585           "description": "Missing or wrong parameters",
 586           "schema": {
 587             "$ref": "../definitions.json#/error"
 588           }
 589         },
 590         "401": {
 591           "description": "Authentication required",
 592           "schema": {
 593             "$ref": "../definitions.json#/error"
 594           }
 595         },
 596         "403": {
 597           "description": "Hold not allowed",
 598           "schema": {
 599             "$ref": "../definitions.json#/error"
 600           }
 601         },
 602         "404": {
 603           "description": "Hold not found",
 604           "schema": {
 605             "$ref": "../definitions.json#/error"
 606           }
 607         },
 608         "500": {
 609           "description": "Internal server error",
 610           "schema": {
 611             "$ref": "../definitions.json#/error"
 612           }
 613         },
 614         "503": {
 615           "description": "Under maintenance",
 616           "schema": {
 617             "$ref": "../definitions.json#/error"
 618           }
 619         }
 620       },
 621       "x-koha-authorization": {
 622         "permissions": {
 623           "reserveforothers": "1"
 624         }
 625       }
 626     }
 627   },
 628   "/holds/{hold_id}/pickup_locations": {
 629     "get": {
 630       "x-mojo-to": "Holds#pickup_locations",
 631       "operationId": "getHoldPickupLocations",
 632       "tags": ["holds"],
 633       "parameters": [
 634         {
 635           "name": "x-koha-override",
 636           "description": "Comma-separated list of overrides (valid values: any)",
 637           "in": "header",
 638           "type": "string",
 639           "required": false
 640         },
 641         {
 642           "$ref": "../parameters.json#/hold_id_pp"
 643         },
 644         {
 645           "$ref": "../parameters.json#/match"
 646         },
 647         {
 648           "$ref": "../parameters.json#/order_by"
 649         },
 650         {
 651           "$ref": "../parameters.json#/page"
 652         },
 653         {
 654           "$ref": "../parameters.json#/per_page"
 655         },
 656         {
 657           "$ref": "../parameters.json#/q_param"
 658         },
 659         {
 660           "$ref": "../parameters.json#/q_body"
 661         },
 662         {
 663           "$ref": "../parameters.json#/q_header"
 664         }
 665       ],
 666       "produces": ["application/json"],
 667       "responses": {
 668         "200": {
 669           "description": "Hold pickup location",
 670           "schema": {
 671             "type": "array",
 672             "items": {
 673               "$ref": "../definitions.json#/library"
 674             }
 675           }
 676         },
 677         "400": {
 678           "description": "Missing or wrong parameters",
 679           "schema": {
 680             "$ref": "../definitions.json#/error"
 681           }
 682         },
 683         "401": {
 684           "description": "Authentication required",
 685           "schema": {
 686             "$ref": "../definitions.json#/error"
 687           }
 688         },
 689         "403": {
 690           "description": "Hold pickup location list not allowed",
 691           "schema": {
 692             "$ref": "../definitions.json#/error"
 693           }
 694         },
 695         "404": {
 696           "description": "Hold not found",
 697           "schema": {
 698             "$ref": "../definitions.json#/error"
 699           }
 700         },
 701         "500": {
 702           "description": "Internal server error",
 703           "schema": {
 704             "$ref": "../definitions.json#/error"
 705           }
 706         },
 707         "503": {
 708           "description": "Under maintenance",
 709           "schema": {
 710             "$ref": "../definitions.json#/error"
 711           }
 712         }
 713       },
 714       "x-koha-authorization": {
 715         "permissions": {
 716           "reserveforothers": "place_holds"
 717         }
 718       }
 719     }
 720   },
 721   "/holds/{hold_id}/pickup_location": {
 722     "put": {
 723       "x-mojo-to": "Holds#update_pickup_location",
 724       "operationId": "updateHoldPickupLocation",
 725       "tags": ["holds"],
 726       "parameters": [
 727         {
 728           "$ref": "../parameters.json#/hold_id_pp"
 729         },
 730         {
 731           "name": "body",
 732           "in": "body",
 733           "description": "Pickup location",
 734           "required": true,
 735           "schema": {
 736             "type": "object",
 737             "properties": {
 738               "pickup_library_id": {
 739                 "type": "string",
 740                 "description": "Internal identifier for the pickup library"
 741               }
 742             },
 743             "additionalProperties": false
 744           }
 745         }
 746       ],
 747       "produces": [
 748         "application/json"
 749       ],
 750       "responses": {
 751         "200": {
 752           "description": "The new pickup location value for the hold",
 753           "schema": {
 754             "type": "object",
 755             "properties": {
 756               "pickup_library_id": {
 757                 "type": "string",
 758                 "description": "Internal identifier for the pickup library"
 759               }
 760             },
 761             "additionalProperties": false
 762           }
 763         },
 764         "400": {
 765           "description": "Missing or wrong parameters",
 766           "schema": {
 767             "$ref": "../definitions.json#/error"
 768           }
 769         },
 770         "401": {
 771           "description": "Authentication required",
 772           "schema": {
 773             "$ref": "../definitions.json#/error"
 774           }
 775         },
 776         "403": {
 777           "description": "Access forbidden",
 778           "schema": {
 779             "$ref": "../definitions.json#/error"
 780           }
 781         },
 782         "404": {
 783           "description": "Hold not found",
 784           "schema": {
 785             "$ref": "../definitions.json#/error"
 786           }
 787         },
 788         "409": {
 789           "description": "Unable to perform action on hold",
 790           "schema": {
 791             "$ref": "../definitions.json#/error"
 792           }
 793         },
 794         "500": {
 795           "description": "Internal error",
 796           "schema": {
 797             "$ref": "../definitions.json#/error"
 798           }
 799         },
 800         "503": {
 801           "description": "Under maintenance",
 802           "schema": {
 803             "$ref": "../definitions.json#/error"
 804           }
 805         }
 806       },
 807       "x-koha-authorization": {
 808         "permissions": {
 809           "reserveforothers": "place_holds"
 810         }
 811       }
 812     }
 813   }
 814 }