belgif
Query parameters for search (comparison, text search, ...)
In GitLab by @wsalembi on Feb 23, 2018, 8:07
Standardize on how to represent 'greater than', 'smaller than or equal than', etcetera in query parameters. Use cases are searches or cursor-based pagination (#2)
In GitLab by @kernixski on Apr 24, 2018, 13:04
For complex queries, we can use FIQL (Feed Item Query Language) or RSQL (a superset of FIQL).
More info on FIQL: https://tools.ietf.org/html/draft-nottingham-atompub-fiql-00
Example of FIQL parsers and some integrations: http://cxf.apache.org/docs/jax-rs-search.html
Example of RSQL parser: https://github.com/jirutka/rsql-parser (also an FIQL parser)
I will try some parsers for next meeting. Sorry.
The API will accept or reject the given criteria. I think there is no standard to list the permitted fields and related operators on those fields. We should find a way to specify it. In the documentation. In an HTTP header ?
This syntax also allow groups and "and" and "or" operators.
An alternative is to define simple query parameters like priceLt, priceLe, priceEq, priceGt, priceGe. But it will maybe not cover all the needs. And the same can be done with RSQL.
In GitLab by @pvdbosch on Apr 24, 2018, 14:43
- simple case - limited list of search parameters:
=> explicit query parameters for each one, defined in Swagger spec.
Example:
?birthDate_lt=
?birthDate_le= gt ge - complex case: long list of search parameters (not necessarily known at design time): FIQL or RSQL => to investigate the differences; check if implementation is usable
In GitLab by @kernixski on May 28, 2018, 15:46
jirutka RSQL parser seems to be used by other projects but the project itself seems to be abandonned (no commit since 2 years).
Here is an example of implementation for the jirutka RSQL parser. It is the implementation for JPA query builder: https://gist.github.com/jirutka/42a0f9bfea280b3c5dca . To use it seems to be very simple. And it is also easy to add our own operators.
Tutorial for jirutka RSQL parser: http://www.baeldung.com/rest-api-search-language-rsql-fiql
There is no standard way to specify which property and which property and which operators can be used. The simplest way to document it is to add them in the text description in the Swagger specifications.
In GitLab by @pvdbosch on May 29, 2018, 15:11
For simple query scenario, two options:
-
?birthDate_lt=
-
?birthDate_contains=
-
?birthDate:lt= ( not HL7)
-
?birthDate:contains= ( ~ HL7 standard)
In GitLab by @pvdbosch on May 29, 2018, 15:47
?birthDate:contains generates birthDatecontains in Java with swagger codegen which is inconvenient.
=> underscore is easier: ?birthDate_lt
In GitLab by @kernixski on Nov 19, 2018, 10:08
mentioned in commit 5d83610a3d2d93f82b41814c332b7c6bda709b93
In GitLab by @kernixski on Nov 19, 2018, 10:27
mentioned in commit bdf0d26cfa387bf8be421bbae2ea1d59ff654004
In GitLab by @pvdbosch on Nov 26, 2018, 14:31
conclusions of the meeting of 19 November:
- underscore confirmed as separator between property and operation
- dot was also considered but it isn't distinguishable from a property when referencing nested properties e.g.
?partner.birthDate.lt=
- dot was also considered but it isn't distinguishable from a property when referencing nested properties e.g.
- wildcards can be supported as value for text search, replacing the need for separate contains/startsWith/endsWith parameters. Escaping for some characters may be necessary.The API doc should document which search types are supported.
In GitLab by @kernixski on Dec 17, 2018, 09:12
mentioned in commit 024fab696927f3b9ed8a5509a70b3a086cd4c1ca
In GitLab by @pvdbosch on Dec 20, 2018, 11:57
Discussed in december meeting: drop the _matches suffix when matching a field (either fully, partially with wildcards, ...)
In GitLab by @kernixski on Jan 21, 2019, 10:22
mentioned in commit f125b9d952d72d2d5aa6f60f9d1ae7d5858889c6
In GitLab by @kernixski on May 13, 2019, 08:12
mentioned in commit acb7b14b1c9fe9a7da7d72c565a8522afad98f30
In GitLab by @kernixski on May 13, 2019, 08:16
mentioned in commit 56dacc2d357690cf3dde6c0abd83b5a537d18848
In GitLab by @kernixski on May 13, 2019, 08:16
mentioned in commit 341ff95580e331b46d8f71f46f54690fe0400139
In GitLab by @kernixski on May 13, 2019, 08:16
mentioned in commit a1717ffdb587c82d545cc97c7166b5ba21196bc9
In GitLab by @kernixski on May 13, 2019, 08:16
mentioned in commit f420beefd59db0d0a172d82ed4c95cae9342a99e
In GitLab by @kernixski on May 13, 2019, 08:16
mentioned in commit 589cf7927e9638f64dc0dd3311e6256e968ade33
In GitLab by @kernixski on May 13, 2019, 10:24
mentioned in commit 4e9c86a3952288182e08cbc782a204a4d9be3fbd
In GitLab by @kernixski on May 13, 2019, 11:21
created merge request !6 to address this issue
In GitLab by @kernixski on May 13, 2019, 11:21
mentioned in merge request !6
In GitLab by @pvdbosch on Nov 19, 2019, 18:04
like mentioned on the merge request !6 : it doesn't contain any commits. Forgotten to push changes?
In GitLab by @pvdbosch on Nov 20, 2019, 14:00
changed title from {-representation of 'greater than', 'smaller than or equal than', ... in-} query parameters to {+'greater than', 'smaller than or equal than', ... as+} query parameters
I recall from our latest meeting that for multiple parameters, it's a burden to define all combinations. In that case, working with brackets could be an alternative.
That page seems an interesting read. The LHS brackets solution seems to have similar consequences as other types of suffixes proposed earlier in this issue: either all of the possible params have to be listed in OpenAPI, or it has to accept any unknown query parameter. The RHS colon solution would enable listing parameters in OpenAPI, without combination for each operator (gt, lt, gte, ...)
We could leave the decision up to the API designer according to context (few combinations: LHS, more combinations: RHS, lots of parameters: search query param)
There's an old branch with some prepared changes that could be taken up again: https://github.com/belgif/rest-guide/compare/master...feature-18