Attachment 126175 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.19 KB, created by Martin Renvoize (ashimema) on 2021-10-13 10:40:04 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Martin Renvoize (ashimema)

Created: 2021-10-13 10:40:04 UTC

Size: 2.19 KB

patch

obsolete

>From ff766bd4b6e6986b2b68245b37cf52e9859087d5 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
>
>---
> api/v1/swagger/swagger.yaml | 28 ++++++++++++++++++++++++++++
> 1 file changed, 28 insertions(+)
>
>diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml
>index b1032ec38e..1c2c85a9ba 100644
>--- a/api/v1/swagger/swagger.yaml
>+++ b/api/v1/swagger/swagger.yaml
>@@ -48,6 +48,34 @@ 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%" }'`
>+
>     ## Special headers
> 
>     ### x-koha-library
>-- 
>2.20.1

Actions: View | Diff | Splinter Review

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