Simpler HTTP API

[rwb27]

Currently, Actions are started with a POST request and immediately return a 201 response with an Invocation object: this is JSON that describes the status of an action. The intention is that, following a POST to start the action, its self link is repeatedly polled until the action is complete.

This is a one-size-fits-all solution that works well for long running actions, that probably produce logs etc. that are worth checking as they go. However, someone implementing a client from scratch would find it annoying to have to parse several responses to get to the action's output. For a short action, it would be much simpler to start the action with POST and receive (perhaps a second or two later) a 200 response with the action's output. If the output is a Blob, the data could be returned directly - e.g. POST to snap_image and receive a jpeg response.

I think the cleanest solution would be to have a response timeout header. This could be a time in seconds, or "immediate" or "never". Selecting "immediate" gives the current behaviour. Selecting "never" gives the second (simpler) behaviour. Selecting a time will use the second behaviour as soon as the action completes, or the first behaviour once the timeout is reached. That was roughly what the first version of labthings did, but it proved to be quite confusing (especially if actions sometimes took longer than the timeout and sometimes didn't).

With regard to returning files directly, perhaps we could also consider the Accept header if present: that way, we could check if the media type is accepted, and if not we default to JSON with a link to download the BLOB. There's a question there as to whether we should assume JSON unless Accept is present, or whether we default to returning data unless Accept: application/json is specified.