Asynchronous HTTP request pattern

Question

Here is the pattern that I thought about for a resource accepting a single asynchronous HTTP request at a time (i.e. a request which has not yet been fulfilled when the response is sent):

1. Create a single process:

   POST /resource → 202 {"monitor": "/process"}
   POST /resource → 409 "A request has already been accepted, retry later."
   

2. Monitor its state:

   GET /process → 200 {"state": "ready"}
   GET /process → 200 {"state": "running", "progress": 0.75}
   GET /process → 200 {"state": "terminated", "product": "/product"}
   

3. Retrieve its product:

   GET /product → 200 foo
   

The product is optional since it depends on the nature of the process (e.g. a video encoding process has a product while a machine shutdown process does not) and only makes sense for the POST method.

And here is the pattern that I thought about for a resource accepting multiple asynchronous HTTP requests at a time:

1. Create multiple processes:

   POST /resource → 202 {"monitor": "/process/123"}
   POST /resource → 202 {"monitor": "/process/456"}
   

2. Monitor their states:

   GET /process/123 → 200 {"state": "ready"}
   GET /process/456 → 200 {"state": "ready"}
   GET /process/123 → 200 {"state": "running", "progress": 0.75}
   GET /process/456 → 200 {"state": "running", "progress": 0.50}
   GET /process/123 → 200 {"state": "terminated", "product": "/product/123"}
   GET /process/456 → 200 {"state": "terminated", "product": "/product/456"}
   

3. Retrieve their products:

   GET /product/123 → 200 foo
   GET /product/456 → 200 bar
   

Again the product is optional since it depends on the nature of the process and only makes sense for the POST method.

Now here are my questions:

1. Are these two patterns the correct way to process asynchronous HTTP requests?
2. Can asynchronous HTTP requests be idempotent?

---

A definition of idempotence is given in RFC 7231, § 4.2.2. ‘Idempotent Methods’:

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. Of the request methods defined by this specification, PUT, DELETE, and safe request methods are idempotent.

So it seems to me that asynchronous HTTP requests cannot be idempotent with the multiple asynchronous HTTP requests pattern, since part of their intended effect is to always create resources on the server (e.g. /process/123 and /product/123). However it seems to me that asynchronous HTTP requests can be idempotent with the single asynchronous HTTP request pattern, depending on their intended effect, since they do not have this systematic resource creation as part of their intended effect.

Answer 1

Are these two patterns the correct way to process asynchronous HTTP requests?

They are a correct way to process asynchronous HTTP requests.

The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled.

Notice that "ought to" is not of the requirements levels described by RFC 2119.

Can asynchronous HTTP requests be idempotent?

Yes.

PUT /announcements HTTP/1.1
Content-Type: text/plain

This is tomorrow's announcement

HTTP/1.1 202 Accepted
Content-Type: text/plain

Maybe I'll do that at midnight.

So it seems to me that asynchronous HTTP requests cannot be idempotent with the pattern accepting multiple asynchronous HTTP requests at a time, since part of their intended effect is to always create resources on the server

Not all asynchronous HTTP requests create unique resources. Upserting or deleting resources can be done asynchronously too.

Also, be aware that the "idempotent" constraint describes the semantics of the request, not the implementation (see Fielding 2002). The semantics of a PUT or DELETE request don't depend on whether the server happens to choose to act on the request at once or accept it for processing later.