2

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?

  • 3
    In case of doubts Postel's law. Anyways, how is people represented without filters? – Laiv Aug 6 '17 at 19:59
  • 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. – toniedzwiedz Aug 14 '17 at 4:52
6

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.

  • How would the array be without filters? – Laiv Aug 6 '17 at 20:04
  • @Laiv: In my version, still grouped on city. Your answer is a good alternative as well. – Bart van Ingen Schenau Aug 7 '17 at 6:08
3

The short answer is no, it's not a good practice. It breaks Postel's law. As @Bart as commented, It would make hard to work with the API.

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

As alternative to the @Bart's answer, I will assume that /people -without filters- doesn't make any kind of grouping.

The easier would be letting users to 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 allways 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.

  • 1
    Postels law, while well intentioned, can also lead to madness. – whatsisname Aug 7 '17 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. – Laiv Aug 7 '17 at 15:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.