From f245cf3f83791129eb4e5d6b8b2c080bf8edf3ab 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 MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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: wainuiwitikapark (cherry picked from commit 534e7bf44a3667046793c07a9f17a4bcc13a3b74) Signed-off-by: Frédéric Demians --- 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 5718ec8ac2..ae4edac15c 100644 --- a/Koha/REST/Plugin/Query.pm +++ b/Koha/REST/Plugin/Query.pm @@ -512,7 +512,8 @@ sub _parse_dbic_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 38bfb5dfff..afb47241aa 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -687,13 +687,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