"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

{...}