We need general guidance for search results

[mwoodiupui]

From time to time we find ourselves debating the same questions about how to respond to unusual search requests. We should have a general policy to guide developers. For example, see DSpace/DSpace#10730.

I suggest that we should distinguish several cases:

• The search context is invalid. For example, a search scope that is defined to be a UUID, but the request presents something that cannot be interpreted as a UUID. This is a truly invalid request, and I would suggest returning status 400 with an explanation: the given scope is not a UUID. Such a request can never produce a result set.
• The search context does not exist. For example, a search scope is defined to be a UUID, the request presented a valid UUID, but no context is named by that UUID. This is a valid request with no result, but has no result because of the context rather than its content. This should return a "good request" status, perhaps 204 with the explanation that there is no result set because there is no such scope. Such a request could produce a result set in the future if that context is created.

Another way of looking at this is that one case means "your client is incorrectly designed" and the other means "your client is confused". In both cases we have found valuable information about why the result set is empty. We should pass that information to the client to help the client's maintainers improve it.

Of course a request with a valid and existing context, which finds nothing, should return status 200: there is a result set (which happens to be empty). IMHO it should be possible for the client to distinguish this case ("I found nothing") from "it was not possible for me to find anything".