Say Goodbye to HTTP URI Query Parameters

New Year is approaching fast but there is still some time to make one more New Year resolution.

Traditionally, when it comes to expressing the search requirements with HTTP URI, one uses URI query name and value, for example:

1. "/search/people?age=30&age=40"
2. "/search/people?ageFrom=30&ageTill=40"

First query can be read like this: "Find all people who are either 30 or 40 years old", the second - "Find all people older than 30 but younger than 40".

Plain query parameters are very widely used and actually very 'capable', one can invent a query parameter such as "ageFrom" to indicate the conditional requirement. It is not quite perfect in that the actual operator is "=" but the name implies it is not "equal to" but "greater or equal to", but it works, and probably reads better in some cases.

That said, the bigger the number of terms, the more tedious it can become to support creating the parameters like "ageFrom" and writing the actual code for figuring out which parameter means whether it is indeed the equality check as in "age=30" or say a "greater than" check as in "ageFrom=30". Supporting the finer-level checks such as "greater or equal to", as well as combining multiple type of checks can indeed become difficult to manage at the code level.

Consider always using FIQL expressions:

1. "/search/people?_s=age==30;age=40"
1.1 "/search/people?age==30;age=40"
1.2 "/search/people/age==30;age=40"

2. "/search/people?_s=age=ge=30;age=lt=40"
2.1 "/search/people?age=ge=30;age=lt=40"
2.2 "/search/people/age=ge=30;age=lt=40"

Does it look more complex ? I don't think it does but I can agree it may look a bit unusual at first, though the syntax is actually very easy to understand after typing it  just for a bit of time.

Note a number of possible variations - in fact I guess I like options 1.2 and 2.2 most, the "optionality" aspect of URI query components does not make the whole URI represent a specific application state very cleanly (options 1, 1.1, 2, 2.1).

Also note the fine-level checks in 2.1/2.2 which are tricky to express with the plain queries, example, in this case it is "Find all people 30 years old or older but younger than 40 (exclusive)".

If you think about it, you have nothing to lose by starting using FIQL, for many cases it is nearly as simple and primitive as using plain query name and value pairs but the bonus comes immediately once you start expressing something more involved. As noted at the beginning of this post, plain queries are also capable in this regard - but the more complex the search requirements are - the less easy it becomes working with the plain queries.

Those Apache CXF users who have started experimenting with FIQL can utilize the existing FIQL converters, which is another plus point, consider the task of writing the code for converting plain query parameters to JPA2 expressions - it can be an involved task indeed - but with CXF JPA2 converter it is a walk in the park; as a side note - JPA2 converter now supports "count" extensions, for example, "find all the people living in London with more than 6 children".

Well, you may not be convinced that it is time to drop plain query name and value pairs. Never mind, just get CXF converting them internally to FIQL (which is very easy to do for CXF given that FIQL is a richer language, and still rely on the handy FIQL converters of your choice to interact with the data stores and completely generalize the search processing logic along the way. Offer different search endpoints for your users to enjoy working with, one accepting the traditional queries and another one accepting FIQL queries, with both endpoints using the same FIQL converters.

Still plenty of options to innovate in this well-explored space :-)!

Update: See also this earlier post from Abhishek Jain.

Happy New Year !