15

I am implementing a REST API which involves creating a object on the server. The object creation involves multiple steps and may take a while. I do not want the user to wait on it. I simply return a 202 response with a unique request id for the client request and start some threads on the server to create the object. The client is supposed to check back to see whether the request is completed or not, in the future. The flow goes like this:

  1. The client POSTs the object.
  2. The server responds with a 202 Accepted code with a Location header /my-app/<reqId>
  3. The client does a GET on /my-app/<reqId>

Now at the third step, these things might happen:

  1. Object creation is still in progress(client should check again after sometime).
  2. Some Error occured.
  3. Object is successfully created.

Now what http code should my API /my-app/<reqId> respond for the above three scenarios?

Improve this question

1 Answer 1

Reset to default
12

I might do it a bit differently from the start. The Location header has a specific meaning, pointing to the actual resource connected to the request, basically the "result" of whatever was requested, not the resource indicating the state of the request itself. This might be a small difference, might nonetheless be confusing later.

Also the specification says the 202 should return content indicating or linking to the "state" resource that describes the progress of the request itself.

So the flow might be:

  1. Client does POST
  2. Server sends 202 Accepted. Location header points to the URI where the requested resource will be (this is not the state), this will be 404 until the processing is done. Also, the content of the 202 might include the "state" representation. The Content-Location header has the link to this "state" resource.
  3. Client GETs the state resource to check on the progress. This resource always exists, so it always returns 200.
  4. If the state indicates success, the resource indicated in the Location now exists, otherwise it will never exist. State resource continues to exists indefinitely.
Improve this answer
Sign up to request clarification or add additional context in comments.

6 Comments

What about errors in creating the actual resource? Should I return a 200 for the 'state' resource with error details in the body of the response?
Yes, as the "state" always exists, there is no error there. If there is an error in the background creation process on the server, it is the content that indicates this, not the protocol itself. As an alternative, you can just check whether the requested resource (the result of the processing) is there. That would be 404 if it is not there, and switch to 200 with content when created. It might however never be created if an error occured.
I'd add that it is useful, and probably recommended at scale, to add instructions on when to check again in the state resources, to protect yourself from being hammered for the answer. This can be done through infrastructure (by using standard last-updated or version headers, and then caching the state response), or by having a field that states when to check again (i.e. date/time) in the response. Both are soft compliance solutions though, that require the client to comply, to work. You can additionally use a throttling policy, if you don't control the client, for enforcement.
Though it might be a late comment .Incase if the there is error posting to resource .How do you update the client .Because you will return the 202 immediately without actually knowing the error ? You are saying if there is an error don't save the status to db or wherever so that get would always return 404 or 200 in case i.e 200 if the resource exists and 404 incase of errors .
Also Client would not know at what time they have to poll for the status .Lets assume if the Client polls immediately it would be 404 but it might be still getting saved in db from the previous call which might lead to wrong interpretation.Any ways to avoid this?
|

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.