What is the correct query parameter for "match-all" in a REST filter when there is a default?

Question

If a REST API endpoint gets all, then filters are easy. Lack of a filter means "get all results".

GET /persons - gets all persons
GET /persons?name=john - gets all persons with name of "john"

But if there is a default, then I need some way to explicitly not set the default filter. Continuing the above example, if each person has a state, "approved" or "pending", and if my system is set such that if I do not explicitly specify a state, it will return all "approved":

GET /persons - gets all approved persons, because defaults to state=approved
GET /persons?state=approved - same thing, gets all approved persons
GET /persons?state=pending - gets all pending persons

How do I get all persons? What if there are 10 possible states? Or 100?

I can think of a few ways:

• GET /persons?state=any - but then I can never use the actual state any
• GET /persons?state=* - would work, but feels strange? Or is it?
• GET /persons?state= - some URL parsing libraries would complain about a blank query parameter, and does this not imply "state is empty" as opposed to "state is anything"?

How do I say in my GET, "override the default for the state to be anything"?

Answer 1

I don't think there is one answer to this question. As long as you document that the default state is approved well I don't think it matter to the clients if you pass any, * etc. All of your proposals are fine except the last one. I don't think that is a good one.

If I was designing the API I would use all and keep this as a standard. I would also recommend to use paging for all endpoints that returns list of elements. I use offset and limit as paging query parameters. In my API I return 20 elements as default if the client haven't specified another paging criteria.

Answer 2

Maybe this could work for you:

• GET /persons?state - gets all persons that have a state name, no matter which value

• GET /persons?state= - gets all persons that have an empty value for the state name

You probably don’t need to differentiate between these two situations, so you could use either one for getting all persons with the state name (I just think that the variant without = is more beautiful).

FWIW, the application/x-www-form-urlencoded format (i.e., typically used in HTML forms) doesn’t differ between an empty and no value.

As far as the URI standard is concerned, this name-value pair syntax in the query component is only a convention anyway, so you can use whichever syntax/semantics you wish.