Long-Running Operations
You'll learn to
- -Answer a slow request at once with 202 Accepted and a Location to check back on
- -Model the work as an operation resource with pending, processing, completed and failed states
- -Explain why terminal states must be final, and why a held-open connection is fragile
Some operations, such as generating a large report, processing a video or running a bulk export, take longer than a client should wait on one open HTTP connection. Treating them as ordinary synchronous requests either times out or forces the client to hold a connection open far longer than is reasonable. The fix is to accept the request immediately and let the client check back on progress.
An Analogy: The Dry Cleaner's Ticket
You drop off a suit, and the shop does not make you stand at the counter for two days. It gives you a ticket with a number. You come back, show the ticket, and hear "not yet", "nearly done" or "here it is". The ticket is the operation resource, and the number is its address.
202 Accepted: "I've Started, Check Back Later"
POST /reports
{"type": "annual_summary", "year": 2025}
HTTP/1.1 202 Accepted
Location: /operations/op_789
{"id": "op_789", "status": "pending"}202 means the request is valid and has been accepted for processing. That is different from 201 (already created) and 200 (already done). The response carries a Location pointing to an operation resource the client can poll, which means to ask repeatedly at intervals. It works like the Location on a 201, except it points to the in-progress work instead of the finished result.
The Operation Resource and Its Terminal States
GET /operations/op_789
HTTP/1.1 200 OK
{"id": "op_789", "status": "processing", "progress_pct": 40}
# ...later...
GET /operations/op_789
HTTP/1.1 200 OK
{
"id": "op_789",
"status": "completed",
"result_url": "/reports/rep_501"
}- -pending: accepted, not yet started.
- -processing: running, optionally with a progress figure.
- -completed: finished successfully. The response should point to the actual result, not make the client guess where it went.
- -failed: finished unsuccessfully. Include enough detail to explain why, using the same error shape as any other failure.
The demo runs the whole exchange against a fake clock. The first call returns 202 with a Location. The client then polls every two simulated seconds, until the status reaches a terminal state.
A terminal state must be genuinely final. A client polling needs to know for certain when to stop, and a status that can flicker back or revert makes that decision unreliable.
For clients that need to react the moment the operation finishes, combine this with a webhook that fires on completion. Polling is the fallback, and the webhook gives immediacy.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design Long-Running Ops in the API Design Lab's Production Patterns act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!