HardExperience level: 8-15 years1 min read

How do you design a REST API for a long-running operation (can't finish in one request)?

Reviewed by Gurusankar M.

Asked inAmazonMicrosoftGoogle
#async api#202 accepted#polling#webhooks#long-running
Report issue

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.

On this page

Concept Made Simple

Coffee Chat Question

“How do you design a REST API for a long-running operation (can't finish in one request)?”

Remember It Faster

Mind Map Answer

Trigger
POST → 202 Accepted + Location
Poll
GET /operations/{id} → status + result
Or push
webhook on completion
Guard
idempotent trigger (no duplicate jobs)

Learn by Doing

Hands-on Keyboard

http
POST /reports        -> 202 Accepted
                        Location: /operations/op_123
GET /operations/op_123 -> 200 { "status":"running" }
                        ... later ...
                     -> 200 { "status":"done", "result":"/reports/9" }

Think Beyond the Expected

What If?

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:

  • 202 Accepted + status URL
  • poll vs webhook
  • idempotent trigger
  • avoid long-held connections
  • operation resource

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

  1. Polling vs webhooks — trade-offs?
  2. How do you make the trigger idempotent?
  3. How do you handle job failure/retry status?

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.
Open inChatGPTGeminiClaude

Was this answer helpful?

Affiliate links

Tools for Your Developer Workspace

Equipment for a comfortable, productive setup.

As an Amazon Associate I earn from qualifying purchases.