How can I implement a RESTful Progress Indicator?

Question

I want my API to be be RESTful

Let say I have started a long running Task with POST and now want to be informed about the progress?

What is the idiomatic REST way to do this?

Poll with GET every 10 seconds?

Answer 1

The response to your

POST /new/long/running/task

should include a Location header. That header will point to an endpoint the client can hit to find out the status of the task. I would suggest your response look something like:

Location: http://my.server/task-status/15
{
    "self": "/task-status/15",
    "status": "running",
    "expectedFinishedAt": <timestamp>
}

Then your client doesn't have to ping arbitrarily, because the server is giving it a hint as to when to check back. Later GETs to /task-status/15 will return updated timestamps. This saves you from having to blindly poll the server. Of course, this works much better if the server has some idea as to how long it will take to finish processing the task.

Answer 2

The way REST works, or rather the mechanism it uses - the HTTPS GET/POST/PUT/DELETE etc. doesn't provide a mechanism to have an event-driven mechanism where the server could send the data to the client. Though, it is theoretically be possible to have client/server functionality in both your server and in your client - though I wouldn't personally endorse this design. So having some sort of a submit API - POST/PUT and then a status query mechanism - GET would do the job.

Answer 3

The client should be the one giving you that information, showing you how many bytes have been sent already to the server. The server should not care about a partially uploaded resource.

That put aside, you will return a "Location" header indicating where is the resource once is created, but not earlier. I mean, when you POST you don´t know which is going to be the address of the resource (that is indicated later in the Location header), so there is no reasonable way of providing an URL to check the status of the upload, because there is no reasonable way of identifying it till is done (you may try crazy things, but it is not recommendable).

Again, the client should give you that feedback, not the server.