Different responses in REST

Question

Let's say I've got a REST endpoint which is returning a list of people from some location, which can be referenced by address.

GET /people?address=London

A response could be:

[{
 "name":"Jane",
 "age":72
},{
 "name":"John",
 "age": "23"
},
....

But let's say there are people from London UK, but there are also matches from other places (like London, Arkansas, US).

Is it OK, that for this case I return a completely different response?

[{
 "address":"London, UK",
 "count":31
},{
 "address":"London, AK, US",
 "age": "12"
}
....

Is this a good practice? Or maybe in the second case I should set a different status code?

• Laiv: In case of doubts Postel's law. Anyways, how is people represented without filters?
• toniedzwiedz: Not sure what this has to do with REST. The question pertains to the modelling of certain data in JSON responses depending on a set of query parameters. That's very generic. Also, the examples you posted seem to contain no hypermedia controls.

Answer 1

Having these completely different kinds of responses for what is essentially the same resource will make it extremely hard for the recipients of the response to do something useful with it.

A better approach would be to essentially merge the two responses:

[{
 "address":"London, UK",
 "count":31,
 "people":[{
 "name":"Jane",
 "age":72
 },{
 "name":"John",
 "age": "23"
 },
 ....
 ]
},{
 "address":"London, AK, US",
 "count": "12",
 "people": [
 ...
 ]
}
.... 

If you now have just one city matching, you could return an array with a single element and still keep the same structure.

• Laiv: How would the array be without filters?
• Bart van Ingen Schenau: @Laiv: In my version, still grouped on city. Your answer is a good alternative as well.

Answer 2

The short answer is no, it's not a good practice. It "breaks" Robustness principle. As @Bart commented, It could make it hard to work with the API.

Mixing both responses seems appropriate, but it depends on the actual people representation.

I will assume that /people -without filters- don't make any kind of grouping. In that case, the easier would be to let users add more filters. For example:

First call

GET /people?address=London
{
 "count": 2,
 [
 { "name":"Jane", "age":72, "address": "London, UK"},
 { "name":"Jhon", "age":18, "address": "London, AK, US"}
 ]
}

Second call

GET /people?address=London,UK
{
 "count": 1,
 [
 { "name": "Jane", "age":72, "address": "London, UK"}
 ]
}

This way, the representation of /people remains the same all the time, with or without filters. And, of course, the status code is always the same too.

---

Note that I have separated London and UK by coma. I don't know if addresses are normalized or not. If they were, we could add one more request param instead. As for instance ?address=X&country=Y.

• whatsisname: Postels law, while well intentioned, can also lead to madness.
• Laiv: Well, the anarchy beneath the inconsistency can too :-). Any principle or good practice can lead us to madness if we strive to follow them all no matter what. For this particular case I thought It was quite doable to stick with the principle.