Attachment 127450 Details for Bug 29183 – Bug 29183: Add some documentation around query filtering

[patch] Bug 29183: Add some documentation around query filtering

Bug-29183-Add-some-documentation-around-query-filt.patch (text/plain), 2.52 KB, created by Kyle M Hall (khall) on 2021-11-08 14:12:54 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Kyle M Hall (khall)

Created: 2021-11-08 14:12:54 UTC

Size: 2.52 KB

patch

obsolete

>From 7ee20154515614467aed1cda57e9eaafd9fa0712 Mon Sep 17 00:00:00 2001
>From: Martin Renvoize <martin.renvoize@ptfs-europe.com>
>Date: Wed, 13 Oct 2021 11:39:27 +0100
>Subject: [PATCH] Bug 29183: Add some documentation around query filtering
>
>Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
>
>Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
>---
> api/v1/swagger/swagger.yaml | 32 ++++++++++++++++++++++++++++++++
> 1 file changed, 32 insertions(+)
>
>diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml
>index 8b4255dcb4..1f75c3511e 100644
>--- a/api/v1/swagger/swagger.yaml
>+++ b/api/v1/swagger/swagger.yaml
>@@ -48,6 +48,38 @@ info:
>     Note: Some routes might offer additional attributes in their error responses but that's
>     subject to change and thus not documented.
> 
>+    ## Filtering responses
>+
>+    The API allows for some advanced response filtering using a json based query syntax that
>+    can be added as a query parameter, `q=` or in the request body.
>+
>+    For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname
>+    matches one of the fields as described in the particular endpoints response object.
>+
>+    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".
>+
>+    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` wilth 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.
>+
>+    ### Examples
>+
>+    The following request would return any patron with firstname "Henry" and lastname "Acevedo";
>+
>+    `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'`
>+
>+    The following request would return any patron whose lastname begins with "Ace";
>+
>+    `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "Ace%" }'`
>+
>+    The following request would return any patron whilse lastname is 'Acevedo' OR 'Bernardo'
>+
>+    `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'`
>+
>     ## Special headers
> 
>     ### x-koha-library
>-- 
>2.30.2

Actions: View | Diff | Splinter Review

Attachments on bug 29183: 126175 | 126176 | 127447 | 127448 | 127450 | 127451