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?

Mundy

Yes, GET the task resoure which should include information about its status. – Venality

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.

Flocculent

yes this would enhance the GET Request and save server resources. Just wondering since I have more request which would profit from a progress indication if Roy Fielding would accept that for these GUI request I would use something like websocckets – Mundy

@Mundy Websockets are not RESTful, but that's fine. Roy's not going to take it personally if you decide REST is not the right implementation for your web service. – Flocculent

What I meant is that the major part of my API is restful only in the progress indicator part I would depart from being RESTFULL. Do you think he would be ok with that? – Mundy

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.

Parmenter

So I see basically my use case is not supported By REST. Right now I am polling the server with Gets every 15 secs. But this has a lot of drawbacks and produces a lot of traffic. I think for this part of my API I have to use something like web sockets. – Mundy

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.

Boltrope

actually I am uploading a file but then a long transformation happens on the server (about 1 to 5 mins). – Mundy