We have a REST api under design, to fetch an entity, eg persons, as follows
GET /endpoint/version/persons/
Now we can get persons who live in a particular city, as follows:
GET /endpoint/version/persons/?city=input_city
We can also get all cities where persons are as follows, this provides person id and the city, person id being unique while city may or may not repeat:
GET /endpoint/version/persons/?fields=city
The question is how should the rest api be designed if we wish to obtain the distinct list of cities?
In other words, something like
GET /endpoint/version/persons/?distinct_fields=city&sort=city
or
GET /endpoint/version/persons/?group_by=city&sort=city&fields=city
In this call we are not interested in the persons per se but the list of distinct cities.
What design would make it pleasant for the developer?
fields
anddistinct fields
, and since I assume you're mapping this onto SQL statements, GROUP BY seems more intuitive to me. DISTINCT probably applies to the entire field set anyway.