"respond-async" HTTP Preference
The 'respond-async' HTTP preference indicates that the client prefers a faster, asynchronous response to a request, rather than potentially waiting a long time for a response.
Writing requests (clients)
Clients should only send respond-async
to a server known to use a process compatible with the client. Consider writing a test that tests the functionality of the server's asynchronous responses, and that client can read the final result.
Clients should also send a wait preference so that fast operations bypass the extra request necessary to process 202 Accepted
.
Reading requests (servers)
Main article: asynchronous responses
If the server has functionality to return 202 Accepted
, in addition to 200 OK
, 201 Created
, or a similar status code that indicates the request was completed successfully, then the presence of the respond-async
preference should cause the server to select the 202 Accepted
variation. Include Preference-Applied: respond-async
in the response to indicate this was a result of the client's request header.
Absent the respond-async
preference, servers should avoid sending 202 Accepted
responses, since clients that do not implement asynchronous responses might see the unknown 2xx status code and treat it the same as a 200 OK, even though the requested action hasn't been completed yet.
Overview table
- Name
- respond-async
- Description
- A 202 Accepted response is preferable to waiting for the final status code.
- Specification
- RFC 7240: Prefer Header for HTTP
Syntax
respond-async = "respond-async"
Example
POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
{...}