api/v1/swagger/paths/holds.json

   1 {
   2   "/holds": {
   3     "get": {
   4       "x-mojo-to": "Holds#list",
   5       "operationId": "listHolds",
   6       "tags": ["holds"],
   7       "parameters": [
   8         {
   9           "name": "hold_id",
  10           "in": "query",
  11           "description": "Internal hold 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           "$ref": "../parameters.json#/q_param"
 126         },
 127         {
 128           "$ref": "../parameters.json#/q_body"
 129         },
 130         {
 131           "$ref": "../parameters.json#/q_header"
 132         }
 133       ],
 134       "produces": ["application/json"],
 135       "responses": {
 136         "200": {
 137           "description": "A list of holds",
 138           "schema": {
 139             "$ref": "../definitions.json#/holds"
 140           }
 141         },
 142         "401": {
 143           "description": "Authentication required",
 144           "schema": {
 145             "$ref": "../definitions.json#/error"
 146           }
 147         },
 148         "403": {
 149           "description": "Hold not allowed",
 150           "schema": {
 151             "$ref": "../definitions.json#/error"
 152           }
 153         },
 154         "404": {
 155           "description": "Borrower not found",
 156           "schema": {
 157             "$ref": "../definitions.json#/error"
 158           }
 159         },
 160         "500": {
 161           "description": "Internal server error",
 162           "schema": {
 163             "$ref": "../definitions.json#/error"
 164           }
 165         },
 166         "503": {
 167           "description": "Under maintenance",
 168           "schema": {
 169             "$ref": "../definitions.json#/error"
 170           }
 171         }
 172       },
 173       "x-koha-authorization": {
 174         "permissions": {
 175           "borrowers": "edit_borrowers"
 176         }
 177       }
 178     },
 179     "post": {
 180       "x-mojo-to": "Holds#add",
 181       "operationId": "addHold",
 182       "tags": ["holds"],
 183       "parameters": [
 184         {
 185           "name": "body",
 186           "in": "body",
 187           "description": "A JSON object containing informations about the new hold",
 188           "required": true,
 189           "schema": {
 190             "type": "object",
 191             "properties": {
 192               "patron_id": {
 193                 "description": "Internal patron identifier",
 194                 "type": "integer"
 195               },
 196               "biblio_id": {
 197                 "description": "Internal biblio identifier",
 198                 "type": [ "integer", "null" ]
 199               },
 200               "hold_date": {
 201                 "description": "The date the hold was placed",
 202                 "type": [ "string", "null" ],
 203                 "format": "date"
 204               },
 205               "item_id": {
 206                 "description": "Internal item identifier",
 207                 "type": [ "integer", "null" ]
 208               },
 209               "pickup_library_id": {
 210                 "description": "Internal library identifier for the pickup library",
 211                 "type": "string"
 212               },
 213               "expiration_date": {
 214                 "description": "Hold end date",
 215                 "type": ["string", "null"],
 216                 "format": "date"
 217               },
 218               "notes": {
 219                 "description": "Notes related to this hold",
 220                 "type": [ "string", "null" ]
 221               },
 222               "item_type": {
 223                 "description": "Limit hold on one itemtype (ignored for item-level holds)",
 224                 "type": [ "string", "null" ]
 225               },
 226               "non_priority": {
 227                 "description": "Set this hold as non priority",
 228                 "type": [ "boolean", "null" ]
 229               }
 230             },
 231             "required": [ "patron_id", "pickup_library_id" ],
 232             "additionalProperties": false
 233           }
 234         },
 235         {
 236           "name": "x-koha-override",
 237           "description": "Comma-separated list of overrides (valid values: any)",
 238           "in": "header",
 239           "type": "string",
 240           "required": false
 241         }
 242       ],
 243       "consumes": ["application/json"],
 244       "produces": ["application/json"],
 245       "responses": {
 246         "201": {
 247           "description": "Created hold",
 248           "schema": {
 249             "$ref": "../definitions.json#/hold"
 250           }
 251         },
 252         "400": {
 253           "description": "Missing or wrong parameters",
 254           "schema": {
 255             "$ref": "../definitions.json#/error"
 256           }
 257         },
 258         "401": {
 259           "description": "Authentication required",
 260           "schema": {
 261             "$ref": "../definitions.json#/error"
 262           }
 263         },
 264         "403": {
 265           "description": "Hold not allowed",
 266           "schema": {
 267             "$ref": "../definitions.json#/error"
 268           }
 269         },
 270         "404": {
 271           "description": "Borrower not found",
 272           "schema": {
 273             "$ref": "../definitions.json#/error"
 274           }
 275         },
 276         "500": {
 277           "description": "Internal server error",
 278           "schema": {
 279             "$ref": "../definitions.json#/error"
 280           }
 281         },
 282         "503": {
 283           "description": "Under maintenance",
 284           "schema": {
 285             "$ref": "../definitions.json#/error"
 286           }
 287         }
 288       },
 289       "x-koha-authorization": {
 290         "permissions": {
 291           "reserveforothers": "1"
 292         }
 293       }
 294     }
 295   },
 296   "/holds/{hold_id}": {
 297     "patch": {
 298       "x-mojo-to": "Holds#edit",
 299       "operationId": "editHold",
 300       "tags": ["holds"],
 301       "parameters": [{
 302           "$ref": "../parameters.json#/hold_id_pp"
 303         }, {
 304           "name": "body",
 305           "in": "body",
 306           "description": "A JSON object containing fields to modify",
 307           "required": true,
 308           "schema": {
 309             "type": "object",
 310             "properties": {
 311               "priority": {
 312                 "description": "Position in waiting queue",
 313                 "type": "integer",
 314                 "minimum": 1
 315               },
 316               "pickup_library_id": {
 317                 "description": "Internal library identifier for the pickup library",
 318                 "type": "string"
 319               },
 320               "suspended_until": {
 321                 "description": "Date until which the hold has been suspended",
 322                 "type": "string",
 323                 "format": "date-time"
 324               }
 325             },
 326             "additionalProperties": false
 327           }
 328         }
 329       ],
 330       "consumes": ["application/json"],
 331       "produces": ["application/json"],
 332       "responses": {
 333         "200": {
 334           "description": "Updated hold",
 335           "schema": {
 336             "$ref": "../definitions.json#/hold"
 337           }
 338         },
 339         "400": {
 340           "description": "Missing or wrong parameters",
 341           "schema": {
 342             "$ref": "../definitions.json#/error"
 343           }
 344         },
 345         "401": {
 346           "description": "Authentication required",
 347           "schema": {
 348             "$ref": "../definitions.json#/error"
 349           }
 350         },
 351         "403": {
 352           "description": "Hold not allowed",
 353           "schema": {
 354             "$ref": "../definitions.json#/error"
 355           }
 356         },
 357         "404": {
 358           "description": "Hold not found",
 359           "schema": {
 360             "$ref": "../definitions.json#/error"
 361           }
 362         },
 363         "500": {
 364           "description": "Internal server error",
 365           "schema": {
 366             "$ref": "../definitions.json#/error"
 367           }
 368         },
 369         "503": {
 370           "description": "Under maintenance",
 371           "schema": {
 372             "$ref": "../definitions.json#/error"
 373           }
 374         }
 375       },
 376       "x-koha-authorization": {
 377         "permissions": {
 378           "reserveforothers": "1"
 379         }
 380       }
 381     },
 382     "put": {
 383       "x-mojo-to": "Holds#edit",
 384       "operationId": "overwriteHold",
 385       "tags": ["holds"],
 386       "description": "This route is being deprecated and will be removed in future releases. Please migrate your project to use PATCH /holds/{hold_id} instead.",
 387       "parameters": [{
 388           "$ref": "../parameters.json#/hold_id_pp"
 389         }, {
 390           "name": "body",
 391           "in": "body",
 392           "description": "A JSON object containing fields to modify",
 393           "required": true,
 394           "schema": {
 395             "type": "object",
 396             "properties": {
 397               "priority": {
 398                 "description": "Position in waiting queue",
 399                 "type": "integer",
 400                 "minimum": 1
 401               },
 402               "pickup_library_id": {
 403                 "description": "Internal library identifier for the pickup library",
 404                 "type": "string"
 405               },
 406               "suspended_until": {
 407                 "description": "Date until which the hold has been suspended",
 408                 "type": "string",
 409                 "format": "date-time"
 410               }
 411             },
 412             "additionalProperties": false
 413           }
 414         }
 415       ],
 416       "consumes": ["application/json"],
 417       "produces": ["application/json"],
 418       "responses": {
 419         "200": {
 420           "description": "Updated hold",
 421           "schema": {
 422             "$ref": "../definitions.json#/hold"
 423           }
 424         },
 425         "400": {
 426           "description": "Missing or wrong parameters",
 427           "schema": {
 428             "$ref": "../definitions.json#/error"
 429           }
 430         },
 431         "401": {
 432           "description": "Authentication required",
 433           "schema": {
 434             "$ref": "../definitions.json#/error"
 435           }
 436         },
 437         "403": {
 438           "description": "Hold not allowed",
 439           "schema": {
 440             "$ref": "../definitions.json#/error"
 441           }
 442         },
 443         "404": {
 444           "description": "Hold not found",
 445           "schema": {
 446             "$ref": "../definitions.json#/error"
 447           }
 448         },
 449         "500": {
 450           "description": "Internal server error",
 451           "schema": {
 452             "$ref": "../definitions.json#/error"
 453           }
 454         },
 455         "503": {
 456           "description": "Under maintenance",
 457           "schema": {
 458             "$ref": "../definitions.json#/error"
 459           }
 460         }
 461       },
 462       "x-koha-authorization": {
 463         "permissions": {
 464           "reserveforothers": "1"
 465         }
 466       }
 467     },
 468     "delete": {
 469       "x-mojo-to": "Holds#delete",
 470       "operationId": "deleteHold",
 471       "tags": ["holds"],
 472       "parameters": [{
 473           "$ref": "../parameters.json#/hold_id_pp"
 474         }
 475       ],
 476       "produces": ["application/json"],
 477       "responses": {
 478         "204": {
 479           "description": "Hold deleted"
 480         },
 481         "401": {
 482           "description": "Authentication required",
 483           "schema": {
 484             "$ref": "../definitions.json#/error"
 485           }
 486         },
 487         "403": {
 488           "description": "Hold not allowed",
 489           "schema": {
 490             "$ref": "../definitions.json#/error"
 491           }
 492         },
 493         "404": {
 494           "description": "Hold not found",
 495           "schema": {
 496             "$ref": "../definitions.json#/error"
 497           }
 498         },
 499         "500": {
 500           "description": "Internal server error",
 501           "schema": {
 502             "$ref": "../definitions.json#/error"
 503           }
 504         },
 505         "503": {
 506           "description": "Under maintenance",
 507           "schema": {
 508             "$ref": "../definitions.json#/error"
 509           }
 510         }
 511       },
 512       "x-koha-authorization": {
 513         "permissions": {
 514           "reserveforothers": "1"
 515         }
 516       }
 517     }
 518   },
 519   "/holds/{hold_id}/priority": {
 520     "put": {
 521       "x-mojo-to": "Holds#update_priority",
 522       "operationId": "updateHoldPriority",
 523       "tags": [
 524         "biblios",
 525         "holds"
 526       ],
 527       "parameters": [
 528         {
 529           "$ref": "../parameters.json#/hold_id_pp"
 530         },
 531         {
 532           "name": "body",
 533           "in": "body",
 534           "description": "An integer representing the new priority to be set for the hold",
 535           "required": true,
 536           "schema": {
 537             "type": "integer"
 538           }
 539         }
 540       ],
 541       "produces": [
 542         "application/json"
 543       ],
 544       "responses": {
 545         "200": {
 546           "description": "The new priority value for the hold",
 547           "schema": {
 548             "type": "integer"
 549           }
 550         },
 551         "401": {
 552           "description": "Authentication required",
 553           "schema": {
 554             "$ref": "../definitions.json#/error"
 555           }
 556         },
 557         "403": {
 558           "description": "Access forbidden",
 559           "schema": {
 560             "$ref": "../definitions.json#/error"
 561           }
 562         },
 563         "404": {
 564           "description": "Biblio not found",
 565           "schema": {
 566             "$ref": "../definitions.json#/error"
 567           }
 568         },
 569         "409": {
 570           "description": "Unable to perform action on biblio",
 571           "schema": {
 572             "$ref": "../definitions.json#/error"
 573           }
 574         },
 575         "500": {
 576           "description": "Internal error",
 577           "schema": {
 578             "$ref": "../definitions.json#/error"
 579           }
 580         },
 581         "503": {
 582           "description": "Under maintenance",
 583           "schema": {
 584             "$ref": "../definitions.json#/error"
 585           }
 586         }
 587       },
 588       "x-koha-authorization": {
 589         "permissions": {
 590           "reserveforothers": "modify_holds_priority"
 591         }
 592       }
 593     }
 594   },
 595   "/holds/{hold_id}/suspension": {
 596     "post": {
 597       "x-mojo-to": "Holds#suspend",
 598       "operationId": "suspendHold",
 599       "tags": ["holds"],
 600       "parameters": [{
 601           "$ref": "../parameters.json#/hold_id_pp"
 602         }, {
 603           "name": "body",
 604           "in": "body",
 605           "description": "A JSON object containing fields to modify",
 606           "required": false,
 607           "schema": {
 608             "type": "object",
 609             "properties": {
 610               "end_date": {
 611                 "description": "Date the hold suspension expires",
 612                 "type": "string",
 613                 "format": "date"
 614               }
 615             },
 616             "additionalProperties": false
 617           }
 618         }
 619       ],
 620       "consumes": ["application/json"],
 621       "produces": ["application/json"],
 622       "responses": {
 623         "201": {
 624           "description": "Hold suspended"
 625         },
 626         "400": {
 627           "description": "Missing or wrong parameters",
 628           "schema": {
 629             "$ref": "../definitions.json#/error"
 630           }
 631         },
 632         "401": {
 633           "description": "Authentication required",
 634           "schema": {
 635             "$ref": "../definitions.json#/error"
 636           }
 637         },
 638         "403": {
 639           "description": "Hold not allowed",
 640           "schema": {
 641             "$ref": "../definitions.json#/error"
 642           }
 643         },
 644         "404": {
 645           "description": "Hold not found",
 646           "schema": {
 647             "$ref": "../definitions.json#/error"
 648           }
 649         },
 650         "500": {
 651           "description": "Internal server error",
 652           "schema": {
 653             "$ref": "../definitions.json#/error"
 654           }
 655         },
 656         "503": {
 657           "description": "Under maintenance",
 658           "schema": {
 659             "$ref": "../definitions.json#/error"
 660           }
 661         }
 662       },
 663       "x-koha-authorization": {
 664         "permissions": {
 665           "reserveforothers": "1"
 666         }
 667       }
 668     },
 669     "delete": {
 670       "x-mojo-to": "Holds#resume",
 671       "operationId": "resumeHold",
 672       "tags": ["holds"],
 673       "parameters": [
 674         {
 675           "$ref": "../parameters.json#/hold_id_pp"
 676         }
 677       ],
 678       "consumes": ["application/json"],
 679       "produces": ["application/json"],
 680       "responses": {
 681         "204": {
 682           "description": "Hold resumed"
 683         },
 684         "400": {
 685           "description": "Missing or wrong parameters",
 686           "schema": {
 687             "$ref": "../definitions.json#/error"
 688           }
 689         },
 690         "401": {
 691           "description": "Authentication required",
 692           "schema": {
 693             "$ref": "../definitions.json#/error"
 694           }
 695         },
 696         "403": {
 697           "description": "Hold not allowed",
 698           "schema": {
 699             "$ref": "../definitions.json#/error"
 700           }
 701         },
 702         "404": {
 703           "description": "Hold not found",
 704           "schema": {
 705             "$ref": "../definitions.json#/error"
 706           }
 707         },
 708         "500": {
 709           "description": "Internal server error",
 710           "schema": {
 711             "$ref": "../definitions.json#/error"
 712           }
 713         },
 714         "503": {
 715           "description": "Under maintenance",
 716           "schema": {
 717             "$ref": "../definitions.json#/error"
 718           }
 719         }
 720       },
 721       "x-koha-authorization": {
 722         "permissions": {
 723           "reserveforothers": "1"
 724         }
 725       }
 726     }
 727   },
 728   "/holds/{hold_id}/pickup_locations": {
 729     "get": {
 730       "x-mojo-to": "Holds#pickup_locations",
 731       "operationId": "getHoldPickupLocations",
 732       "tags": ["holds"],
 733       "parameters": [
 734         {
 735           "name": "x-koha-override",
 736           "description": "Comma-separated list of overrides (valid values: any)",
 737           "in": "header",
 738           "type": "string",
 739           "required": false
 740         },
 741         {
 742           "$ref": "../parameters.json#/hold_id_pp"
 743         },
 744         {
 745           "$ref": "../parameters.json#/match"
 746         },
 747         {
 748           "$ref": "../parameters.json#/order_by"
 749         },
 750         {
 751           "$ref": "../parameters.json#/page"
 752         },
 753         {
 754           "$ref": "../parameters.json#/per_page"
 755         },
 756         {
 757           "$ref": "../parameters.json#/q_param"
 758         },
 759         {
 760           "$ref": "../parameters.json#/q_body"
 761         },
 762         {
 763           "$ref": "../parameters.json#/q_header"
 764         }
 765       ],
 766       "produces": ["application/json"],
 767       "responses": {
 768         "200": {
 769           "description": "Hold pickup location",
 770           "schema": {
 771             "type": "array",
 772             "items": {
 773               "$ref": "../definitions.json#/library"
 774             }
 775           }
 776         },
 777         "400": {
 778           "description": "Missing or wrong parameters",
 779           "schema": {
 780             "$ref": "../definitions.json#/error"
 781           }
 782         },
 783         "401": {
 784           "description": "Authentication required",
 785           "schema": {
 786             "$ref": "../definitions.json#/error"
 787           }
 788         },
 789         "403": {
 790           "description": "Hold pickup location list not allowed",
 791           "schema": {
 792             "$ref": "../definitions.json#/error"
 793           }
 794         },
 795         "404": {
 796           "description": "Hold not found",
 797           "schema": {
 798             "$ref": "../definitions.json#/error"
 799           }
 800         },
 801         "500": {
 802           "description": "Internal server error",
 803           "schema": {
 804             "$ref": "../definitions.json#/error"
 805           }
 806         },
 807         "503": {
 808           "description": "Under maintenance",
 809           "schema": {
 810             "$ref": "../definitions.json#/error"
 811           }
 812         }
 813       },
 814       "x-koha-authorization": {
 815         "permissions": {
 816           "reserveforothers": "place_holds"
 817         }
 818       }
 819     }
 820   },
 821   "/holds/{hold_id}/pickup_location": {
 822     "put": {
 823       "x-mojo-to": "Holds#update_pickup_location",
 824       "operationId": "updateHoldPickupLocation",
 825       "tags": ["holds"],
 826       "parameters": [
 827         {
 828           "$ref": "../parameters.json#/hold_id_pp"
 829         },
 830         {
 831           "name": "body",
 832           "in": "body",
 833           "description": "Pickup location",
 834           "required": true,
 835           "schema": {
 836             "type": "object",
 837             "properties": {
 838               "pickup_library_id": {
 839                 "type": "string",
 840                 "description": "Internal identifier for the pickup library"
 841               }
 842             },
 843             "additionalProperties": false
 844           }
 845         }
 846       ],
 847       "produces": [
 848         "application/json"
 849       ],
 850       "responses": {
 851         "200": {
 852           "description": "The new pickup location value for the hold",
 853           "schema": {
 854             "type": "object",
 855             "properties": {
 856               "pickup_library_id": {
 857                 "type": "string",
 858                 "description": "Internal identifier for the pickup library"
 859               }
 860             },
 861             "additionalProperties": false
 862           }
 863         },
 864         "400": {
 865           "description": "Missing or wrong parameters",
 866           "schema": {
 867             "$ref": "../definitions.json#/error"
 868           }
 869         },
 870         "401": {
 871           "description": "Authentication required",
 872           "schema": {
 873             "$ref": "../definitions.json#/error"
 874           }
 875         },
 876         "403": {
 877           "description": "Access forbidden",
 878           "schema": {
 879             "$ref": "../definitions.json#/error"
 880           }
 881         },
 882         "404": {
 883           "description": "Hold not found",
 884           "schema": {
 885             "$ref": "../definitions.json#/error"
 886           }
 887         },
 888         "409": {
 889           "description": "Unable to perform action on hold",
 890           "schema": {
 891             "$ref": "../definitions.json#/error"
 892           }
 893         },
 894         "500": {
 895           "description": "Internal error",
 896           "schema": {
 897             "$ref": "../definitions.json#/error"
 898           }
 899         },
 900         "503": {
 901           "description": "Under maintenance",
 902           "schema": {
 903             "$ref": "../definitions.json#/error"
 904           }
 905         }
 906       },
 907       "x-koha-authorization": {
 908         "permissions": {
 909           "reserveforothers": "place_holds"
 910         }
 911       }
 912     }
 913   }
 914 }