Microservice Patterns
Asynchronous Request-Reply
For work that takes seconds or minutes, answer at once with 202 Accepted and a status URL, do the work in the background, and let the client poll or be notified — instead of holding a connection open until something times out.
What you will learn
- Explain why long synchronous requests fail behind proxies and exhaust threads.
- Implement 202 Accepted, a status endpoint and a result location.
- Choose a polling interval or a push notification.
- Handle retries and duplicate submissions safely.
Before you start
Overview
When you drop a suit at the dry cleaner, you do not wait at the counter for two days. You get a ticket, go home, and call or check online until it says "ready".
HTTP is request-response, and every hop on the way — browser, CDN, load balancer, gateway — has a timeout, often 30–60 s or less. Holding a request open for a long job also pins a server thread or connection. With asynchronous request-reply, the API validates the request, enqueues the work and returns 202 Accepted with a status URL. The client polls that URL (respecting Retry-After) or receives a callback; when done, the status points to the result.
Run it
Users start report exports that take 4–8 s, behind a proxy that cuts connections after 10 s. Compare failures and API thread use in A, then the number of Status polls in B and C.
The flow
POST /exports→ validate, store a job, enqueue →202 Accepted,Location: /exports/42/status,Retry-After: 2.GET /exports/42/status→200 {"status":"running"}while in progress.- When finished →
303 See Other,Location: /exports/42/file(or200with a result link); on failure, a status with the error. - The client downloads the result; the job record expires after a retention period.
Implementation
@PostMapping("/exports")
ResponseEntity<Void> start(@RequestBody ExportRequest req, @RequestHeader("Idempotency-Key") String key) {
Job job = jobs.findByKey(key).orElseGet(() -> jobs.create(key, req)); // same key → same job
queue.send("exports", job.id());
return ResponseEntity.accepted()
.location(URI.create("/exports/" + job.id() + "/status"))
.header(HttpHeaders.RETRY_AFTER, "2").build();
}
@GetMapping("/exports/{id}/status")
ResponseEntity<JobStatus> status(@PathVariable String id) {
Job job = jobs.get(id);
if (job.isDone()) return ResponseEntity.status(HttpStatus.SEE_OTHER).location(URI.create("/exports/" + id + "/file")).build();
return ResponseEntity.ok().header(HttpHeaders.RETRY_AFTER, "2").body(job.status());
}Trade-offs
| Benefits | Costs | |
|---|---|---|
| Reliability | No proxy timeouts, no threads held; work survives client disconnects. | Job state must be stored and expired; more endpoints to secure. |
| Latency | The API answers in milliseconds. | Results are noticed up to one poll interval late. |
| Client effort | Standard HTTP semantics. | Clients must implement polling or callbacks and handle failures. |
Production considerations
- Require an Idempotency-Key so a retried POST does not start a second job.
- Authorise status and result URLs: job ids must not be guessable or shareable by accident.
- Put the work on a durable queue (queue-based load leveling), not an in-memory executor.
- Return Retry-After and rate-limit status endpoints to keep polling cheap.