From d8dfcd9b30e80a06ba5a4bec01f9f2fdad84a13d Mon Sep 17 00:00:00 2001 From: Martin Renvoize 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 --- 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.32.0