How do you design a REST API for a long-running operation (can't finish in one request)?
Reviewed by Gurusankar M.
⚡ Short Answer
Don't block the request. Return 202 Accepted with a status URL (Location). The client polls GET /operations/{id} for state (pending/succeeded/failed) and the result link — or you notify via webhook on completion. Make the trigger idempotent so retries don't start duplicate jobs.
☕Coffee Chat Question
Concept Made Simple
“How do you design a REST API for a long-running operation (can't finish in one request)?”
🧠Mind Map Answer
Remember It Faster
⌨️Hands-on Keyboard
Learn by Doing
POST /reports -> 202 Accepted
Location: /operations/op_123
GET /operations/op_123 -> 200 { "status":"running" }
... later ...
-> 200 { "status":"done", "result":"/reports/9" }🔥What If?
Think Beyond the Expected
Why not just hold the HTTP connection open until the job finishes?
Long-held connections hit client/proxy/gateway timeouts, tie up server threads, and can't survive a restart or retry safely. The async (202 + poll/webhook) pattern decouples request duration from job duration and is resilient to retries and failures.
😂Real World
Report generation, video processing, bulk imports use 202 + status resource (or webhooks); cloud APIs (AWS, GCP) expose exactly this 'operation resource' pattern for long tasks.
🎯Interviewer's Expectation
Keywords they're listening for:
⚠️Common Mistakes
- ✗Blocking the request until completion (timeouts)
- ✗Non-idempotent trigger spawning duplicate jobs
- ✗No way to query job status
✅Best Practices
- ✓Return 202 + a queryable operation resource
- ✓Offer webhooks for completion
- ✓Make the trigger idempotent
🔁Follow-up Questions
- 1Polling vs webhooks — trade-offs?
- 2How do you make the trigger idempotent?
- 3How do you handle job failure/retry status?
🧩Related Technologies
Continue Learning with AI
Take this question deeper with your favourite AI assistant. Pick a depth, copy the prompt, or open it directly — AI is your learning companion, not a shortcut.
Plain-language foundations
I'm preparing for a software engineering interview and want to understand this from scratch, as a beginner. Topic: Idempotency (REST APIs) Interview question: "How do you design a REST API for a long-running operation (can't finish in one request)?" Please: 1. Explain the core idea in simple, plain language, using an everyday analogy. 2. Define any technical terms you use. 3. Walk through one small, concrete example. 4. Finish with a single sentence I can easily remember. Keep the tone friendly and assume I'm new to this topic.
Was this answer helpful?
⭐ Featured Products
Support our platform by exploring our recommended products.
As an Amazon affiliate, purchases through these links may earn us a small commission — at no extra cost to you. It helps keep Full Stack Interview Guru free.