Long-running operations (async responses) in Rest API

Introduction

Sometimes, tasks take a long time to finish. Long-running operations let the server start the task and tell you to check back later for the result.

Uploading a large file that takes minutes to process.

Starting a video conversion that needs time to complete.

Running a complex report that takes a while to generate.

Processing data that requires heavy calculations.

Any task where waiting for the response would make the app slow or unresponsive.

Syntax

Rest API

POST /start-task HTTP/1.1
Host: example.com

Response:
HTTP/1.1 202 Accepted
Location: /task-status/12345

The server responds with status 202 to say it accepted the request but is still working.

The Location header gives a URL where you can check the task status later.

Examples

The client asks to convert a video. The server replies with 202 and a URL to check progress.

Rest API

POST /convert-video HTTP/1.1
Host: example.com

Response:
HTTP/1.1 202 Accepted
Location: /status/convert-789

The client checks the status URL and sees the task is still running.

Rest API

GET /status/convert-789 HTTP/1.1
Host: example.com

Response:
HTTP/1.1 200 OK
{
  "status": "processing"
}

Later, the client checks again and sees the task is done with a link to the result.

Rest API

GET /status/convert-789 HTTP/1.1
Host: example.com

Response:
HTTP/1.1 200 OK
{
  "status": "done",
  "result_url": "/videos/converted-789.mp4"
}

Sample Program

This example shows starting a report generation, then checking its status twice: once while it's running, and once when it's done with a download link.

Rest API

POST /start-report HTTP/1.1
Host: example.com

Response:
HTTP/1.1 202 Accepted
Location: /report-status/555

---

GET /report-status/555 HTTP/1.1
Host: example.com

Response:
HTTP/1.1 200 OK
{
  "status": "in_progress"
}

---

GET /report-status/555 HTTP/1.1
Host: example.com

Response:
HTTP/1.1 200 OK
{
  "status": "completed",
  "download_link": "/reports/report-555.pdf"
}

Important Notes

Always check the Location header to know where to poll for updates.

Use status codes like 202 to tell the client the task is accepted but not finished.

Polling too often can overload the server; use reasonable delays between checks.

Summary

Long-running operations let servers handle slow tasks without making clients wait.

Clients start the task and get a URL to check progress later.

This keeps apps responsive and user-friendly.