From e7b3d05bc740b459d0c700545c8c280a14fe72ad Mon Sep 17 00:00:00 2001 From: Martin Renvoize Date: Wed, 10 Jul 2024 09:39:33 +0100 Subject: [PATCH] Bug 37018: Clarify operators This patch clarifies the list of operators both in the validate routine and in the swagger descrption block where we document this feature for the end user. JD amended patch: tidy Signed-off-by: Jonathan Druart Signed-off-by: Lucas Gass --- Koha/REST/Plugin/Query.pm | 3 ++- api/v1/swagger/swagger.yaml | 16 +++++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/Koha/REST/Plugin/Query.pm b/Koha/REST/Plugin/Query.pm index b492866770..cfabc44d31 100644 --- a/Koha/REST/Plugin/Query.pm +++ b/Koha/REST/Plugin/Query.pm @@ -664,7 +664,8 @@ sub _rewrite_related_metadata_query { sub _validate_operator { my ($operator) = @_; my %allowed_operators = - map { $_ => 1 } qw(= != < > <= >= like -not_like -in -ident -bool -not_bool -or -like -not -and -regexp); + map { $_ => 1 } + qw(= != < > <= >= -in -ident -bool -not_bool -or like -like -not_like -between -not_between -not -and -regexp); Koha::Exceptions::REST::Query::InvalidOperator->throw( operator => $operator ) unless exists $allowed_operators{$operator}; return; diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml index 7352b1c240..be75d4dbd4 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -1000,13 +1000,27 @@ info: We can refine that with more complex matching clauses by nesting a the clause into the object; `{ "fieldname": { "clause": "value" } }`. - Available matching clauses include `>`, `<`, `>=`, `<=`, `-like`, and `-not_like`. + Available matching clauses include `=`, `!=`, `<`, `>`, `<=`, `>=` and `-not`. We also support `-like` + and `-not_like` string comparisons with `%` used to denote wildcards, thus you can pass + `{ "fieldname": { "-like": "value%" } }` to do a 'starts with' string match for example. We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH` level will result in an "AND" query, whilst combinding them in an `ARRAY` will result in an "OR" query: `{ "field1": "value2", "field2": "value2" }` will filter the response to only those results with both field1 containing value2 AND field2 containing value2 for example. + There is a collection of special operators also available to you, including: + + * `-in` - Expects an array of values to perform an OR match against + * `-not_in` - Expects an array of values to perform a NOR match against + * `-between` - Expects two values which the value of the field is expected to fall between + * `-not_between` - Expects two values which the value of the field is expected to fall outside of + * `-ident` - Expects a second field name to match the two field values against + * `-regexp` - Expects a perl compatible regular expression for which the value should match + + Logic and nesting is also supported and you may use `-and` and `-or` to change the logic of an ARRAY + or HASH as described above. + Additionally, if you are requesting related data be embedded into the response one can query on the related data using dot notation in the field names. -- 2.39.5