users@jersey.java.net

[Jersey] Grouped Parameters

From: Ron <webron_at_gmail.com>
Date: Wed, 9 May 2012 00:18:32 +0300

Hi everyone,

We have a new use-case in our application that I was hoping to hear some
suggestions from other developers.

Assume a list operation where you can add filters to affect the content of
the list.
For those of you with a LinkedIn account, run the following URL, for
example:

http://www.linkedin.com/search/fpsearch?type=people&keywords=sharon&pplSearchOrigin=GLHD

This gives you a list of people with the name 'Sharon'. On the left side,
there's a nice long list of filters. We're looking to implement some
similar functionality.

There are three types of filters:
1. Boolean - true/false.
2. Multi-options - one or more values of a given list.
3. Range - dates, numbers and so on.

The API call itself has additional parameters such a search string, paging
support and more (just to emphasize that there's more than just the filters
as parameters).
Since we try to adhere to the *basic* REST guidelines, since this is a list
operation the HTTP method used is GET (in other words, no body).
Another point to keep in mind is that we have multiple list API calls for
different data types, where some filters are the same and some are unique
to the specific data type. The number of filters can be around 20.

We're looking for a clean solution that will hopefully give us the
following results:
1. Create a clear API call, easy for our clients to implement.
2. Create an API call that creates a reasonable method signature
(hopefully, one that won't take half a page due to the number of filters).
3. Limit the usage of only the relevant filters in a given list call.
4. Hopefully require us little manual parsing to some sort of a filter
object.
5. Be easily documented by automatic documentation tools such as Enunciate
or Swagger.
6. Easy to maintain in case of adding or removing a filter from the list.

We thought of using the @MatrixParam but that doesn't solve all the issues,
especially #3 (of course we can manually filter the filters - but that may
be cumbersome). I'd love to hear additional ideas and suggestions that will
hopefully comply to as many of the requirements we have as possible.

Thanks,
Ron