# Long-Running Operations and Bulk Requests — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/rel-async-bulk

> Return quickly with 202 and a status resource, and design bulk endpoints deliberately.

## Do not make clients wait on a socket

When work takes more than a few seconds (video processing, large exports, report generation), accept the request, respond **`202 Accepted`** with a `Location` pointing to a **status resource** (`/exports/exp_9`), and let the client poll it (`pending`, `running`, `succeeded` with a result link, or `failed` with a problem) or receive a **webhook** on completion. Include a `Retry-After` hint for polling. For **bulk** operations (create 500 items), decide the semantics up front: all-or-nothing, or per-item results (a `207`-style list of successes and failures), cap the batch size, and make each item idempotent. Bulk endpoints reduce round trips but add complexity, so offer them only where clients truly need them.

## The 202 flow

Illustrative HTTP exchange; the demo API does not implement exports.

```text
POST /v1/exports          {"report": "orders", "month": "2026-09"}
<- 202 Accepted
   Location: /v1/exports/exp_9
   Retry-After: 5

GET /v1/exports/exp_9
<- 200 {"id":"exp_9","status":"running","progress":0.4}

GET /v1/exports/exp_9      (later)
<- 200 {"id":"exp_9","status":"succeeded","download_url":"https://files.example.com/exp_9.csv"}
```

**Quiz:** What should an API return for a request that will take minutes to finish?

- [ ] 200 after blocking for minutes
- [x] 202 Accepted with a Location for a status resource
- [ ] 204 and forget it
- [ ] 401

*Answer:* 202 Accepted with a Location for a status resource. Acknowledge quickly and let the client check progress separately.