Error response need precise definition

[diekhans]

The expected error responses from the API need precise definition to allow implementing consistent behavior between server.

[diekhans]

@sarahhunt describes search error behavior of Ensemb implementation of API in ga4gh/ga4gh-server#576 (comment)

re searching for something that doesn't exist - We're currently returning HTTP/1.0
400 Bad Request and an endpoint specific error message. It seems more useful for the client to
highlight the problem rather than leaving them to test for empty sets.

I agree, error handling needs to be specified exhaustively.

@diekhans would have expected an empty set.

[jeromekelleher]

There's a sublety here @diekhans. Suppose we have SearchReadGroupSetsRequest, which has two fields datasetId and name. Now, suppose we set datasetId to "someIdThatDoesNotExist" and send off the request. I would argue that the response should be a 404, "dataset does not exist". On the other hand, if we set datasetId to a dataset that does exist and name to a value that does not, I think the result should be the empty list, and not an error.

[diekhans]

that is more intuitive!! I would agree that searching within a dataset
that doesn't exist is an error, searching for a dataset that doesn't
exist seems to be an empty results.

Jerome Kelleher notifications@github.com writes:

There's a sublety here @diekhans. Suppose we have SearchReadGroupSetsRequest,
which has two fields datasetId and name. Now, suppose we set datasetId to
"someIdThatDoesNotExist" and send off the request. I would argue that the
response should be a 404, "dataset does not exist". On the other hand, if we
set datasetId to a dataset that does exist and name to a value that does not, I
think the result should be the empty list, and not an error.

—
Reply to this email directly or view it on GitHub.*

[sarahhunt]

So is the suggestion GET's on non-existent ids and POST searches within non-existent sets 404 while bad filters on existing sets silently return empty sets?

We are currently returning 400's and messages like 'The specified callSets are not available in the specified variantSets' when inappropriate filters are applied to make it obvious what's going on. A 400 does seem a little strong, but it's easier to debug.

[jeromekelleher]

I think this seems semantically reasonable @sarahhunt --- I think there are plenty situations where a programmer might search for something and expect to find an empty set of results. I don't think it's an error for a search to produce zero results. (However, I don't think a search should produce zero results when there is an error!)

[diekhans]

Sarah Hunt notifications@github.com writes:

So is the suggestion GET's on non-existent ids and POST searches within
non-existent sets 404 while bad filters on existing sets silently return empty
sets?

That is my intuition, it's not an error to have a filter that
doesn't match. I don't think of that as `bad', but just not
have. It is an error to dereference an object that doesn't
exist.

SQL selects that don't match data just return empty sets.

select * from hg2038.gbCdnaInfo where mrnaAcc = "sarah";
ERROR 1146 (42S02): Table 'hg2038.gbCdnaInfo' doesn't exist

vs
select * from hg38.gbCdnaInfo where acc = "sarah";
Empty set (0.03 sec)

[sarahhunt]

This sounds fine. When the behaviour is documented, it will be easier to work out why empty results are returned.

[calbach]

Absolutely agree with 'empty results' behavior rather than a 404 in the case where you've sent a valid query but the result set is empty.

[mlin]

FWIW here's where we take care of the equivalent blocking-and-tackling (short of the semantic questions discussed above) of defining error responses in our API: https://wiki.dnanexus.com/API-Specification-v1.0.0/Protocols#Errors

Then, our individual API methods list the errors they can produce: e.g. https://wiki.dnanexus.com/API-Specification-v1.0.0/GenomicTables#API-method:-/gtable-xxxx/addRows

Hope this is helpful as an example.