FlowAPI response codes

[jc-harrison]

The number of FlowMachine query states has grown over time, and the HTTP status codes returned by FlowAPI don't necessarily reflect the query state in the most helpful way.

Successful, authorised requests to one of the run/poll/get_result endpoints currently get responses with the following codes, according to the query state when the request is made:

	run	poll	get_result
known	202 Accepted	404 Not Found	404 Not Found
queued	202 Accepted	202 Accepted	202 Accepted
executing	202 Accepted	202 Accepted	202 Accepted
completed	202 Accepted	303 See Other	200 OK
errored	202 Accepted	500 Internal Server Error	403 Forbidden
cancelled	202 Accepted	500 Internal Server Error	500 Internal Server Error
resetting	202 Accepted	404 Not Found	500 Internal Server Error
unknown	202 Accepted	404 Not Found	404 Not Found

I think the response status codes should be:

	run	poll	get_result
known	202 Accepted	404 Not Found	404 Not Found
queued	202 Accepted	202 Accepted	404 Not Found
executing	202 Accepted	202 Accepted	404 Not Found
completed	303 See Other	303 See Other	200 OK
errored	500 Internal Server Error	500 Internal Server Error	404 Not Found
cancelled	409 Conflict	404 Not Found	404 Not Found
resetting	503 Service Unavailable	503 Service Unavailable	404 Not Found
unknown	202 Accepted	404 Not Found	404 Not Found

[greenape]

Yep. Those look appropriate to me I think..

[greenape]

Hmm. Actually after reflecting on this a little more, I don't agree with the run route responses - all of those require an extra communication with flowmachine that adds unnecessary additional responsibility to run, and to anything which is a client of run.

[jc-harrison]

As of #2052, 202 is appropriate for running a cancelled query. I'd accept that 202 is also appropriate when running a completed query. I still think 500 and 503 are appropriate for running errored/resetting queries, respectively - in those situations the query can't be run, so a response indicating a successful run request would be misleading.

[jc-harrison]

Actually, I think polling a query while it's resetting should return 404 - meaning the result is unavailable and won't become available without running the query first (as is the case for "known", "cancelled" and "unknown").

So:

	run	poll	get_result
known	202 Accepted	404 Not Found	404 Not Found
queued	202 Accepted	202 Accepted	404 Not Found
executing	202 Accepted	202 Accepted	404 Not Found
completed	202 Accepted	303 See Other	200 OK
errored	500 Internal Server Error	500 Internal Server Error	404 Not Found
cancelled	202 Accepted	404 Not Found	404 Not Found
resetting	503 Service Unavailable	404 Not Found	404 Not Found
unknown	202 Accepted	404 Not Found	404 Not Found