I think more is needed w.r.t. describing how async works. I would prefer a model like:
- request is sent to the server
- 202 Accepted is returned + Location header for the client to check status
- even if the Location is the same URL as the resource itself
- in the case of a failed create(), the resource at the Location URL still exists but with the failed status and error message. How long it lives for is an impl detail. But this is also a good reason to NOT let the client pass in the ID and use it as part of the URL of resource. Let each create result in a new resource.
- in the case of an async delete(), a GET on the resource will always return at least the status section until the resource is gone - then a 404 would be returned.
I think more is needed w.r.t. describing how async works. I would prefer a model like: