Bug 36641: Add endpoint for fetching circulation rules

This patch adds an endpoint for fetching ciruclations rules given the
constraints of the passed parameters.

We optionally expect item_type, library and patron_category as query
parameters and we return a list of relevant circulation rules pertaining
to that combination of requirements.

You can also add a list of `rules` as a query parameter to limit the
response to only the rules you are interested in for this combination.

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Katrin Fischer <katrin.fischer@bsz-bw.de>

Koha/REST/V1/CirculationRules.pm

@@ -21,7 +21,6 @@ use Mojo::Base 'Mojolicious::Controller';
 
 use Koha::CirculationRules;
 
-
 =head1 API
 
 =head2 Methods
@@ -36,9 +35,77 @@ sub get_kinds {
     my $c = shift->openapi->valid_input or return;
 
     return $c->render(
-        status => 200,
+        status  => 200,
         openapi => Koha::CirculationRules->rule_kinds,
     );
 }
 
+=head3 list_effective_rules
+
+List all effective rules for the requested patron/item/branch combination
+
+=cut
+
+sub list_effective_rules {
+    my $c = shift->openapi->valid_input or return;
+
+    my $item_type       = $c->param('itemtype');
+    my $branchcode      = $c->param('library');
+    my $patron_category = $c->param('category');
+    my $rules           = $c->param('rules') // [ keys %{ Koha::CirculationRules->rule_kinds } ];
+
+    if ($item_type) {
+        my $type = Koha::ItemTypes->find($item_type);
+        return $c->render_invalid_parameter_value(
+            {
+                path   => '/query/item_type',
+                values => {
+                    uri   => '/api/v1/item_types',
+                    field => 'item_type_id'
+                }
+            }
+        ) unless $type;
+    }
+
+    if ($branchcode) {
+        my $library = Koha::Libraries->find($branchcode);
+        return $c->render_invalid_parameter_value(
+            {
+                path   => '/query/library',
+                values => {
+                    uri   => '/api/v1/libraries',
+                    field => 'library_id'
+                }
+            }
+        ) unless $library;
+    }
+
+    if ($patron_category) {
+        my $category = Koha::Patron::Categories->find($patron_category);
+        return $c->render_invalid_parameter_value(
+            {
+                path   => '/query/patron_category',
+                values => {
+                    uri   => '/api/v1/patron_categories',
+                    field => 'patron_category_id'
+                }
+            }
+        ) unless $category;
+    }
+
+    my $effective_rules = Koha::CirculationRules->get_effective_rules(
+        {
+            categorycode => $patron_category,
+            itemtype     => $item_type,
+            branchcode   => $branchcode,
+            rules        => $rules
+        }
+    );
+
+    return $c->render(
+        status  => 200,
+        openapi => $effective_rules ? $effective_rules : {}
+    );
+}
+
 1;

api/v1/swagger/definitions/circ-rule-kind.yaml

@@ -10,6 +10,6 @@ properties:
         - branchcode
         - categorycode
         - itemtype
-additionalProperties: false
+additionalProperties: true
 required:
   - scope

api/v1/swagger/paths/circulation-rules.yaml

@@ -1,32 +0,0 @@
----
-/circulation-rules/kinds:
-  get:
-    x-mojo-to: CirculationRules#get_kinds
-    operationId: getCirculationRuleKinds
-    tags:
-      - circulation_rules
-    summary: Get circulation rules kinds
-    produces:
-      - application/json
-    responses:
-      "200":
-        description: A map of rule kind information
-        schema:
-          type: object
-          additionalProperties:
-            $ref: "../swagger.yaml#/definitions/circ-rule-kind"
-      "403":
-        description: Access forbidden
-        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"

api/v1/swagger/paths/circulation_rules.yaml

@@ -0,0 +1,97 @@
+---
+/circulation_rules:
+  get:
+    x-mojo-to: CirculationRules#list_effective_rules
+    operationId: listCirculationRules
+    tags:
+      - circulation_rules
+    summary: Get circulation rules for this item/library/patron combination
+    produces:
+      - application/json
+    parameters:
+      - name: item_type
+        in: query
+        description: The itemtype
+        required: false
+        type: string
+      - name: library
+        in: query
+        description: The library code
+        required: false
+        type: string
+      - name: patron_category
+        in: query
+        description: The patron category
+        required: false
+        type: string
+      - name: rules
+        in: query
+        description: A comma-separated list of rule kinds
+        required: false
+        type: array
+        items:
+          type: string
+        collectionFormat: multi
+    responses:
+      "200":
+        description: A list of rules for this itemtype, library and patron category combination
+        schema:
+          type: object
+          additionalProperties:
+            type: [ 'string', 'integer' ]
+      "400":
+        description: Bad request
+        schema:
+          $ref: "../swagger.yaml#/definitions/error"
+      "403":
+        description: Access forbidden
+        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:
+        - circulate: circulate_remaining_permissions
+/circulation_rules/kinds:
+  get:
+    x-mojo-to: CirculationRules#get_kinds
+    operationId: getCirculationRuleKinds
+    tags:
+      - circulation_rules
+    summary: Get circulation rules kinds
+    produces:
+      - application/json
+    responses:
+      "200":
+        description: A map of rule kind information
+        schema:
+          type: object
+          additionalProperties:
+            $ref: "../swagger.yaml#/definitions/circ-rule-kind"
+      "403":
+        description: Access forbidden
+        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:
+        - circulate: circulate_remaining_permissions

api/v1/swagger/swagger.yaml

@@ -283,8 +283,10 @@ paths:
     $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal"
   "/checkouts/availability":
     $ref: "./paths/checkouts.yaml#/~1checkouts~1availability"
-  /circulation-rules/kinds:
-    $ref: ./paths/circulation-rules.yaml#/~1circulation-rules~1kinds
+  /circulation_rules:
+    $ref: ./paths/circulation_rules.yaml#/~1circulation_rules
+  /circulation_rules/kinds:
+    $ref: ./paths/circulation_rules.yaml#/~1circulation_rules~1kinds
   /cities:
     $ref: ./paths/cities.yaml#/~1cities
   "/cities/{city_id}":