From 0117fbf1844c68219c0dd8f74ce2dafc89239992 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. --- Koha/REST/Plugin/Query.pm | 2 +- api/v1/swagger/swagger.yaml | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/Koha/REST/Plugin/Query.pm b/Koha/REST/Plugin/Query.pm index b4928667705..9664d56fe74 100644 --- a/Koha/REST/Plugin/Query.pm +++ b/Koha/REST/Plugin/Query.pm @@ -664,7 +664,7 @@ 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 9bd863c073a..e70861f8c9a 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -1016,13 +1016,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.45.2