An asynchronous API accepts work and returns before that work is complete. It is useful when an operation cannot reliably finish within the HTTP response window or when buffering and independent scaling matter. The key contract is that “accepted” means durably recorded—not merely received—and that the caller can later inspect the operation’s outcome.
Why move long-running work out of the request?
With a synchronous request, a client waits while the server performs the operation. If the connection times out, the client may not know whether the server never received the request, accepted it, or completed the work but lost the response. A timeout is not a reliable outcome.
| # | Preview | Product | Price | |
|---|---|---|---|---|
| 1 |
|
API Design Patterns | $59.99 | Buy on Amazon |
| 2 |
|
The Design of Web APIs, Second Edition | $50.14 | Buy on Amazon |
| 3 |
|
Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges... | $54.46 | Buy on Amazon |
| 4 |
|
API Design for C++ | $89.24 | Buy on Amazon |
| 5 |
|
Designing Web APIs: Building APIs That Developers Love | $25.49 | Buy on Amazon |
The asynchronous request-reply pattern gives the operation its own lifecycle: the API acknowledges acceptance, and the client obtains the result later. Microsoft’s Asynchronous Request-Reply Pattern describes this approach for long-running work; AWS also outlines asynchronous communication patterns in its communication patterns guidance.
This is not automatically better for every endpoint. If work reliably finishes within the response window and the caller needs the result immediately, a synchronous response may be simpler. Asynchrony is most useful when latency is unpredictable, work benefits from buffering, or producers and workers need to scale independently.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
Define the operation contract before choosing a queue
A queue is only one component. Callers also need clear acceptance semantics, a way to identify and inspect work, and a defined outcome when processing fails.
- The client submits a request to start an operation.
- The API validates it and durably records the operation, typically alongside placing work on a queue.
- Only after that durable step succeeds, the API responds that the request was accepted and provides an operation identifier or status location.
- A worker processes the operation and updates its state, such as pending, running, succeeded, or failed.
- The client checks the status resource or receives a completion notification.
For example, an API might respond with an accepted status and a URL for the operation resource. That resource should say whether work is pending, in progress, complete, or failed; it can also expose useful progress or timing information. The exact response codes and fields should be part of the API’s documented contract, not inferred by clients.
Acceptance must follow durable persistence. If an API returns “accepted” before the operation is safely recorded, a process crash can erase work the client believes was queued. AWS discusses durable acknowledgments and status handling in its asynchronous communication guidance.
Rank #2
Make cancellation semantics explicit
An operation resource can expose cancellation, but “cancel” needs a precise meaning. Work might stop before execution, stop partway through, or be too late to interrupt. If partial changes have already occurred, cancellation may require rollback or compensating actions. State what callers can expect rather than presenting cancellation as a guaranteed undo.
Make client retries safe with idempotency
Suppose the API accepts a POST, but its response is lost. A client that retries cannot tell from the timeout alone whether it is submitting new work or repeating an accepted request. Without deduplication, the service may enqueue and execute the same logical operation twice.
Have clients send an idempotency key—a request identifier that the service associates with the operation. When the same request is retried with the same key, return the existing operation or its current status instead of creating another one. Amazon’s guidance on safe retries with idempotent APIs explains why the key and the operation’s effects need to be recorded consistently.
- Choose a scope: Define whether keys are unique per account, endpoint, or another boundary.
- Set retention: Keep keys long enough to cover the retry period your clients may use, and specify what happens after expiry.
- Handle changed input: Define whether reuse of a key with different parameters is rejected or handled by an explicit rule. Do not silently treat a different request as the original.
- Keep the record and work creation consistent: A key record without the corresponding operation—or an operation created without its key—can break deduplication during failures.
This is a contract for safe, externally observable retries, not a promise that a distributed queue will execute a message exactly once. Workers and downstream calls can fail or repeat; design effects to tolerate retries and document how duplicate submissions are recognized.
Use buffering without letting the backlog run away
A queue decouples API producers from workers and can absorb bursts, allowing each side to scale independently. The tradeoff is that queued work still consumes capacity and time: a growing backlog means callers wait longer for completion. AWS describes an API-to-SQS integration in its API Gateway with SQS pattern; the same architectural principle applies beyond that particular service.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Client → API → durable queue → workers → operation status
Rank #4
Do not interpret buffering as unlimited capacity. Set operational controls around the queue and the operation lifecycle:
- Measure queue depth and age: The age of the oldest work item often makes user-visible delay clearer than depth alone. Track processing latency as well.
- Bound admission: Use queue limits, rate limits, or other admission control to prevent overload from turning into an unbounded backlog. Fail fast or reject new work when the system cannot accept it safely.
- Limit retries and use backoff: Repeated immediate retries can worsen an outage. Define retry limits and delays for transient failures.
- Handle poison or repeatedly failing work: Define dead-letter handling and a reviewed redrive process so failures do not loop indefinitely or disappear without visibility.
- Manage stale work: Work that is no longer useful should be discarded, expired, or deprioritized according to a clear policy.
- Keep status aligned with reality: Ensure the operation resource reflects queued, running, and terminal states so callers do not mistake a delay for completion.
AWS Well-Architected’s REL05-BP04 guidance on queue limits covers queue latency, stale work, and dead-letter/redrive handling. Queue limits are an availability control as well as a capacity setting: they help prevent the system from accepting more work than it can process usefully.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose how callers learn that work is complete
Completion delivery is a separate design choice from accepting and processing the request. Choose a channel based on how quickly clients need updates, their ability to receive them, expected concurrency, and the operational burden the service can support.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
| Approach | How it works | Benefits | Costs and concerns |
|---|---|---|---|
| Periodic polling | Client requests the operation status at intervals. | Simple to implement; works with ordinary HTTP clients. Requests can be rate-limited or served with cache-aware behavior where appropriate. | Creates repeated requests and may delay detection of completion until the next check. |
| Long polling | Client holds a status request open until a change occurs or a timeout is reached. | Can reduce repeated checks while still using a request-reply interaction. | Requires careful timeout and connection management at clients, servers, and intermediaries. |
| Callback or webhook | Service sends a completion notification to a client-provided endpoint. | Client need not repeatedly ask for updates. | Service must handle delivery retries and timeouts, and secure the destination and notification path. |
| Bidirectional connection | Service sends updates over a maintained connection. | Can support interactive or ongoing updates. | Adds connection state, ordering, and reconnection or recovery concerns. |
AWS’s asynchronous communication guidance and Microsoft’s request-reply pattern overview describe these kinds of completion approaches and their tradeoffs. Whichever channel you choose, keep the operation status resource authoritative: notifications can be delayed or missed, and clients need a way to reconcile their view with the service’s state.
Decide whether asynchrony fits the workload
Before adding a queue, answer the contract and failure questions that determine whether the design will be useful:
- Can the operation finish predictably inside the HTTP response window, and does the caller need the final result immediately?
- What durable action has completed when the API says the request is accepted?
- How does a retry identify an existing operation, and what happens if a key is reused with changed input?
- What happens when the queue backs up, a worker repeatedly fails, or work becomes stale?
- How will a caller inspect progress, learn of completion, and understand a terminal failure?
- Can callers cancel work, and what does cancellation mean after partial effects?
If these questions have clear answers, asynchronous request-reply can improve responsiveness and separate the scaling of request handling from background processing. If they do not, adding a queue merely moves the uncertainty out of the HTTP request and into the system’s state, retries, and operations.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
