Bug 38253: Add lowest priority REST API endpoint for holds

This patch adds a new endpoint to toggle the lowest priority of a hold via the REST API.

To test:
1) Apply the patch
2) perl build-resources.PL
3) prove t/db_dependent/api/v1/holds.t

Sponsored-by: Koha-Suomi Oy
Signed-off-by: David Nind <david@davidnind.com>
Signed-off-by: Pedro Amorim <pedro.amorim@ptfs-europe.com>
Signed-off-by: Katrin Fischer <katrin.fischer@bsz-bw.de>

Koha/REST/V1/Holds.pm

@@ -536,4 +536,28 @@ sub update_pickup_location {
     };
 }
 
+=head3 lowest_priority
+
+Method that handles toggling the lowest priority of a Koha::Hold object
+
+=cut
+
+sub lowest_priority {
+    my $c = shift->openapi->valid_input or return;
+
+    my $hold_id = $c->param('hold_id');
+    my $hold    = Koha::Holds->find($hold_id);
+
+    return $c->render_resource_not_found("Hold")
+        unless $hold;
+
+    return try {
+        C4::Reserves::ToggleLowestPriority($hold_id);
+        $hold->discard_changes;    # refresh
+        return $c->render( status => 200, openapi => $hold_id );
+    } catch {
+        $c->unhandled_exception($_);
+    };
+}
+
 1;

api/v1/swagger/paths/holds.yaml

@@ -761,3 +761,54 @@
     x-koha-authorization:
       permissions:
         reserveforothers: place_holds
+"/holds/{hold_id}/lowest_priority":
+  put:
+    x-mojo-to: Holds#lowest_priority
+    operationId: toggleLowestPriority
+    tags:
+      - holds
+    summary: Toggle holds lowest priority
+    parameters:
+      - $ref: "../swagger.yaml#/parameters/hold_id_pp"
+      - name: body
+        in: body
+        description: An integer representing the new priority to be set for the hold
+        required: false
+        schema:
+          type: integer
+    produces:
+      - application/json
+    responses:
+      "200":
+        description: Toggle the holds lowest priority value
+        schema:
+          type: integer
+      "401":
+        description: Authentication required
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "403":
+        description: Access forbidden
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "404":
+        description: Hold not found
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "409":
+        description: Unable to perform action on hold
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "500":
+        description: |
+          Internal server error. Possible `error_code` attribute values:
+          * `internal_server_error`
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "503":
+        description: Under maintenance
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+    x-koha-authorization:
+      permissions:
+        reserveforothers: modify_holds_priority

api/v1/swagger/swagger.yaml

@@ -401,6 +401,8 @@ paths:
     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1priority"
   "/holds/{hold_id}/suspension":
     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1suspension"
+  "/holds/{hold_id}/lowest_priority":
+    $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1lowest_priority"
   /ill/backends:
     $ref: ./paths/ill_backends.yaml#/~1ill~1backends
   "/ill/backends/{ill_backend_id}":

t/db_dependent/api/v1/holds.t

@@ -17,7 +17,7 @@
 
 use Modern::Perl;
 
-use Test::More tests => 14;
+use Test::More tests => 15;
 use Test::MockModule;
 use Test::Mojo;
 use t::lib::TestBuilder;
@@ -1497,3 +1497,55 @@ subtest 'delete() tests' => sub {
 
     $schema->storage->txn_rollback;
 };
+
+subtest 'PUT /holds/{hold_id}/lowest_priority tests' => sub {
+
+    plan tests => 5;
+
+    $schema->storage->txn_begin;
+
+    my $password = 'AbcdEFG123';
+
+    my $library_1 = $builder->build_object( { class => 'Koha::Libraries', value => { pickup_location => 1 } } );
+
+    my $patron = $builder->build_object( { class => 'Koha::Patrons', value => { flags => 0 } } );
+    $patron->set_password( { password => $password, skip_validation => 1 } );
+    my $userid = $patron->userid;
+    $builder->build(
+        {
+            source => 'UserPermission',
+            value  => {
+                borrowernumber => $patron->borrowernumber,
+                module_bit     => 6,
+                code           => 'modify_holds_priority',
+            },
+        }
+    );
+
+    # Disable logging
+    t::lib::Mocks::mock_preference( 'HoldsLog',      0 );
+    t::lib::Mocks::mock_preference( 'RESTBasicAuth', 1 );
+
+    my $biblio = $builder->build_sample_biblio;
+
+    # biblio-level hold
+    my $hold = Koha::Holds->find(
+        AddReserve(
+            {
+                branchcode     => $library_1->branchcode,
+                borrowernumber => $patron->borrowernumber,
+                biblionumber   => $biblio->biblionumber,
+                priority       => 1,
+                itemnumber     => undef,
+            }
+        )
+    );
+
+    $t->put_ok( "//$userid:$password@/api/v1/holds/0" . "/lowest_priority" )->status_is(404);
+
+    $t->put_ok( "//$userid:$password@/api/v1/holds/" . $hold->id . "/lowest_priority" )->status_is(200);
+
+    is( $hold->discard_changes->lowestPriority, 1, 'Priority set to lowest' );
+
+    $schema->storage->txn_rollback;
+};