CODEWITHSUNDEEP
web-servicesapirestasynchronous
ChrisM
ChrisM

Reputation: 2248

Implementing an asynchronous web API

We are developing a web API which processes potentially very large amounts of user-submitted content, which means that calls to our endpoints might not return immediate results. We are therefore looking at implementing an asynchronous/non-blocking API. Currently our plan is to have the user submit their content via:

POST /v1/foo

The JSON response body contains a unique request ID (a UUID), which the user then submits as a parameter in subsequent polling GETs on the same endpoint:

GET /v1/foo?request_id=<some-uuid>

If the job is finished the result is returned as JSON, otherwise a status update is returned (again JSON).

(Unless they fail both the above calls simply return a "200 OK" response.)

Is this a reasonable way of implementing an asynchronous API? If not what is the 'right' (and RESTful) way of doing this? The model described here recommends creating a temporary status update resource and then a final result resource, but that seems unnecessarily complicated to me.

Upvotes: 2

Views: 161

Answers (1)

benjiman
benjiman

Reputation: 4048

Actucally the way described in the blog post you mentioned is the 'right' RESTful way of processing aysnchronous operations. I've implemented an API that handles large file uploads and conversion and does it this way. In my opinion this is not over complicated and definitely better then delaying the response to the client or something.

Some additional note: If a task has failed, I would also return 200 OK together with a representation of the task resource and the information that the resource creation has failed.

Upvotes: 2

Related Questions