3

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?

Improve this question
2
  • 3
    In case of doubts Postel's law. Anyways, how is people represented without filters? Commented Aug 6, 2017 at 19:59
  • 1
    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. Commented Aug 14, 2017 at 4:52

2 Answers 2

Reset to default
8

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.

Improve this answer
2
  • How would the array be without filters? Commented Aug 6, 2017 at 20:04
  • @Laiv: In my version, still grouped on city. Your answer is a good alternative as well. Commented Aug 7, 2017 at 6:08
4

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.

Improve this answer
2
  • 1
    Postels law, while well intentioned, can also lead to madness. Commented Aug 7, 2017 at 4:29
  • 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. Commented Aug 7, 2017 at 15:04

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.