REST API Structure to request multiple items

Question

I have a REST API that looks something like the below where a person can belong to an organisation (but doesn't have to) and a person has many items. The items may also belong to the organisation instead of the person.

/people/:personId
/people/:personId/items
/organisations/:orgId/items
/organisations/:orgId/people/:personId/items

There is a scenario where we want to query the items for multiple people within an organisation, what's the correct URL structure to use?

Option 1

/organisations/:orgId/people/items?personId=1&personId=2

Option 2

/organisations/:orgId/items?personId=1&personId=2

Option 3

/items?personId=1&personId=2

Answer 1

It really doesn't matter that much. Your URL is just a 'unique resource locator' the format you use is up to you. Go with what you are most confortable with and your users will understand.

Having said that I'd go with ?personId=1&personid=2 just because its easy to parse/read

take a look at this similar question

Answer 2

I would possibly do something similar to how Microsoft deals with choosing pages to print. An example of this is:

To show user 3

...?show=3

To show all users from 10-50

...?show=10-50

To show user 1 to 3 and 5 and 10 to 20

...?show=1-3,5,10-20

It gives complete freedom and can be developed quite easily.

For completeness, I've deviced a simple example in Javascript:

var input = "3,4,5,10-20,55".split(',');
var complete = [];

for (var x = 0; x < items.length; x++) {
  var item = input[x];
  if (item.contains("-")) {
    var range = item.split("-");
    for (var i = range[0]; i <= range[1]; i++) {
      complete.push(i);
    }
  } else {
    complete.push(item);
  }
}

console.log(complete); //["3", "4", "5", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "55"]