Advanced paging, sorting and filtering in REST API design

Question

In REST API, it is considered a good practice to handle sorting, filtering and pagination of collections using URI query parameters, like:

GET /employees?offset=30&limit=15&name=Mary&sort=-surname

Unfortunately, in some "advanced" cases, the number of parameters may "explode", so that this solution is not possible any more.

Back to the previous example, suppose that we want to apply some more sophisticated filters on many other fields (eg.: address contains "NY", age > 30, age <= 40, (marital status is "married" AND salary<100000USD) OR (marital status is "divorced" AND salary>=100000USD), and many other... ).

Clearly, in such a case, a simple set of query parameters is not suitable.

How such a situation should be designed? Maybe the client should send a POST containing some structured data representing the query? Is there any more-or-less standard agreement on how to design such queries?

Thanks!

Answer 1

One approach is to make search filters a REST resource meaning creating new REST methods:

• POST /filters, expecting a body with filters, e.g. (marital status is "married" AND salary<100000USD) OR (marital status is "divorced" AND salary>=100000USD) and returning the unique id of this search, and (to avoid a roundtrip to the server) the first results, and links to the next results
• GET /filters/<id>/<offset>, returning the results for search id starting from offset

Answer 2

Have you tried posting a body with filters?

{
  "age": {
    "$gte": 30,
    "$lte": 40
  },
  "status": {
    "$in": [
        "Divorced",
        "Single"
    ]
  }
}