Skip to content
API Design Learn/Production REST II: Correctness & Scale
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Long-Running Operations

3 min read

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"

Accepting the request immediately, without doing the work synchronously
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

Polling the operation resource for status
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.

Press Run: accepted at once, polled until it is completed

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.

Ready to Build This?

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.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!