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?
5
The question is how should the rest api be designed if we wish to obtain the distinct list of cities?
GET /cities
Trying to do a God resource that returns all your resources depending on the query string is a bad idea and breaks REST principles.
Query strings should filter the specific collection of a resource (ie turn all people into a specific subset of people), not be used to determine which resource you are trying to get in the first place. Each resource should have a specific URL. A collection of people having its own URL is ok, but having both cities and people resources at the same URL is confusing and adds complexity to the client implementation.
You should also not build your URL scheme around a single possible use case of the client. Let the client worry about why it wants a resource. By expecting the client to get Cities via the People you are forcing client designers to understand that on your system that is how you get cities.
One final point unrelated to the question but still important. Using query strings to filter the data returned (ie ?field=city) is a design smell. The content type negotiation should determine how the resource looks to the client, if the client wants the representation in a specific format it should tell the server this via the header, not the URL. The reason for this is again not to add business level complexity to the URL scheme.
4