Include Search Status in Result

[jeffkinnison]

Having the additional status endpoint is a bit cumbersome when trying to run a search. The status information is pertinent as a condition even if the search is complete, and having it simplifies the process of both checking on in-progress searches and retrieving cached results.

I propose eliminating the /parallels/xxxxxx/status endpoint and rolling that information into the /parallels/xxxxxx endpoint to simplify the search cycle for API users.

[nOkuda]

One of the concerns I have with implementing the status+results proposal is that it would not be RESTful. The endpoint is named such that that the resource expected is the results of the search. So combining the status with the results seems like we're mixing resources where they shouldn't be mixing. (However, https://softwareengineering.stackexchange.com/a/316412 seems to argue that updating the resource with status information does not mess with the status code semantics, which might lead to an argument that this approach is still RESTful).

That said, I admit that my design is not as good as it could have been. I remember finding my design cumbersome as well when I was testing to make sure it worked. https://farazdagi.com/2014/rest-and-long-running-jobs/ and http://restalk-patterns.org/long-running-operation-polling.html both propose creating a job queue resource to handle the search submission and status updates at a separate endpoint from the final results. I think this would alleviate the unintuitive snag of my design while keeping the API RESTful. (The Hacker News discussion of the first link might (https://news.ycombinator.com/item?id=18568461 have helpful insight if we decide to go this route.) The only complaint I have about this method is the automatic redirect to the results on requesting a GET on the job status. Instead of a redirect, I think it should return the job status and provide a way to navigate to the results resource.

So the status+results approach would streamline the API experience by taking out the status endpoint but might not be RESTful; the job queue approach seems RESTful and might be slightly more streamlined than the current implementation, but wouldn't eliminate the extra step. I'm inclined to go with the job queue approach for the RESTfulness, but would that be enough of an enhancement for the API experience to warrant the change?

[jeffkinnison]

Handled a while ago.