`single.*` vs `list.*`

[SimonGoring]

I'm not clear on why people would use the single method in the API call. Are there actually cases where people only want a single response for an API call, without knowing how many occurrences actually exist?

[mmcclenn]

The 'single' operation is used to fetch details about a single occurrence when you know its identifier. You could also use the 'list' operation for this purpose, but 'single' emphasizes that you are asking for, and guaranteed to get, a single record in response.

[SimonGoring]

I'm going to reopen this.

I think that use case is potentially problematic, and I think it results in a non-standard API structure. Because they're using single, they'd never know if (potentially) many more records might be returned.

So, let's say I "know" that there's only one "Hermidivores" occurrence, so I use single.json for my queries to (speed things up?). If there's some sort of re-alignment of taxa in the DB, then I might be making an inappropriate assumption, but I'd never know because my code would always "just work".

Maybe I'm not clear what the benefit of allowing only a single response is. Is it that then you don't have to test its length in the subsequent code?

[mmcclenn]

No, that's not how it works. The single operation takes an entirely different set of parameters than the list operation. The former only accepts a single identifier, and either returns information about the corresponding record or else a 404 error if no record was found. The latter takes many different parameters for filtering the available set of records and returns anywhere from zero to all of the records.

These are two entirely different kinds of transactions, which is why the API provides two separate operations.