Specify a number of items or all items in REST API request

Question

I am designing an API and am wondering the best practice for values that can either specify a number or a list of items, or just specify that it is 'all' of those items.

For example imagine an endpoint /analyze that allows you to analyaze a document for specific categories. A sample request might be:

{
   "documentId": "my-doc",
   "numberOfLines": 100,
   "categories": ["category1", "category2"]
}

What would be the best way to signify that I want all lines and all categories? Have multiple types for the same value like this seems like a bad pattern:

{
    "documentId": "my-doc",
    "numberOfLines": "all",
    "categories": "all"
}

Is it best to have something like null or -1 signify all. I don't like this because it could cause errors if that logic is missed by the handler:

{
    "documentId": "my-doc",
    "numberOfLines": null, //null to mean all
    "categories": null // null to mean all
}

Just set "categories" to an empty list. This can indicate "all" and don't worry about what the value of "numberOfLines" is. — jiveturkey, Apr 14 '20 at 14:23
I would reserve the empty list to specify no categories. Not sure what you mean by not worrying what the value of "numberOfLines" is as this represents a meaningful value, otherwise it would not be included in the request. — iain, Apr 14 '20 at 15:00
If you are receiving "categories:[]" who cares what "numberOfLines" is, return them all. But you are using it for no categories. Which by the way makes me wonder why a request would even be sent. — jiveturkey, Apr 14 '20 at 15:13
sorry, the example might be confusing. The numberOfLines is how many lines in the document you want to look at. The categories is which categories you want to look for in those lines. They are independent of each other. — iain, Apr 14 '20 at 15:16

Evert · Accepted Answer · 2020-04-27T17:17:55.663

I don't think there's anything wrong with using the string all here. Type systems like Typescript, and validation systems like JSON Schema can easily express this, and it's way more descriptive than an empty array, -1, or null.

Using codes like -1 is a bit of a leftover from earlier times when saving a few bytes was important, but it's hard to tell by eying it what it could mean. One alternative that's also fairly obvious is asterisk *.

score 0 · Answer 2 · answered Apr 14 '20 at 14:27

It depends on what behaviour you want to encourage. If expected default behaviour is to fetch all with just a possibility to filter I would make these parameter optional - i.e.

{
   "documentId": "my-doc",
}

Would be valid request, and would work the same as

{
   "documentId": "my-doc",
   "numberOfLines": null, //null to mean all
   "categories": null // null to mean all
}

On the other hand if you want clients to restrict payload by default with only only special use cases where someone might want all data IMHO it's file to introduce "magic words" e.g.

{
   "documentId": "my-doc",
   "numberOfLines": "IReallyReallyWantAllData",
   "categories": "IReallyReallyWantAllData"
}

The "magic words" approach causes the problem of different data types. That makes for verbose and clunky parsing of the request objects. — iain, Apr 14 '20 at 14:57

Specify a number of items or all items in REST API request

2 Answers2