Resources that accept
PATCH requests block on the request until the operation completes. A client may not want to wait, so a resource can offer the Async profile to give the client control over if they wait at all or time out after a specified number of seconds. Async profile lets the client “fire and forget” the state change operation.
The Async resource accepts the state change request, and the affected resource may eventually reflect the state modification in the request. Async
POST operations return a
Location header, while async
PATCH operations will not. This profile offers no guarantees or timelines as to how long it takes for the operation to complete, nor offer any channel to communicate success or failure of the operation. A client must determine eventual success by examining the state of the changed/deleted resource, ideally via Entity validation headers, or examining the
Clients use the Async profile in situations where an operation may take a long time to complete, and the client merely does not want to wait. The Async resource validates the request, including header validation (for example, when Entity or Preflight profiles are mixed in) and body syntax checking, if relevant. The client must know if they have made a mistake with their request before the async operation initiates.
Batch- or job-style APIs, where normal behaviour is to submit a state change that is processed sometime in the future, should not use the Async profile. That API should have semantics that manages the job and provides job status over time.
Resources that support the Async profile include in the Async profile header in it’s list of
In this flow, the client does not want to wait for the operation to complete or time out; they get an immediate acceptance of the operation from the resource. The client sends a
Prefer: respond-async header to tell the resource to return as soon as it can confirm the operation’s acceptance. The resource returns a status of
The client sends a
Prefer: respond-async; wait=#seconds header indicating that they want to wait for a set number of seconds for a complete response. If the operation exceeds the
wait time and the operation is still ongoing, the resource responds with
202 Accepted. The wait time is suggestive, not a guaranteed service level.
When Async is mixed in with Entity or Preflight profiles, the client can expect header validation to occur before the async operation response returns. The client’s request is valid from the perspective of the mixins before the request is considered Accepted. If a mixin’s header validation fails, the request fails with their specific status response.
The Preflight mixin has a two-step flow. The client preflights the request with
Expect and omitting
Prefer. On success, the client sends the async request in the second call. The first call cannot be asynchronously accepted.
HTTP/1.1 Semantics and Content: RFC 7231
- 200 OK: section 6.3.1
- 201 Created: section 6.3.2
- 202 Accepted: section 6.3.3
- 204 No Content: section 6.3.5
Prefer Header for HTTP: RFC 7240
- Preference-Applied: section 3
- The respond-async preference: section 4.1
- The wait preference: section 4.3
Copyright © 2019 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.