Examples of reliable simple query languages
nmoreaud opened this issue · comments
Hello,
In this section, you recommend to design simple query languages using query parameters.
I have seen multiple custom query languages in different Rest APIs, that badly handle literal escaping and data types.
Do you have examples of well designed query languages?
Are there projects with reference implementation and grammars available somewhere?
Here are some interesting articles on the subject:
https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#97-filtering
https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/#filtering
https://github.com/kriszyp/rql
We had something far less complex in mind than your links are pointing to and had hoped that our description in #236 makes this pretty clear.
When we talk about a simple query language, we talk about very simple name/value-pairs, that users can intuitively interpreted. Something like name_pattern (or name_regex), created_after (or created_between), or colors (for a comma separated list of colors a garment can have).
The idea is that a query parameter consisting of a small number of _-separated words, that give enough context to intuitively understand the property the filter is working on as well as the format used to filter values.
Yes, what @tkrop mentioned is correct: We had an simple QL in mind for queries passed via the URL query params.
But we were not very specific in defining this QL, and instead preferred QL design hints without clear restrictions.
@nmoreaud I agree that more specific guidance could be helpful for API consumers and providers.
I have also seen bad syntax for handling of separators, operators and values, and find the links you provided interesting.
Would you be interested in drafting a PR update of #236 ?
What syntax variant you would favor due to what trade-off considerations?
@nmoreaud we have improved the example on simple query language. Would you like to contribute an update for the complex query language to guide users how to design this case properly? Else we would suggest to close the issue.