Card 02/ 09
Answering a Long Job With 202 Accepted and a Status Resource
The server accepts the job, returns a link to its status, and the client checks that link until the job ends.
The standard shape for an asynchronous operation is a 202 Accepted response carrying a Location header that points at a new status resource, which the client reads until the job ends and which then links to the result. Here is the yearly report from the previous scenario as an asynchronous job. The paths and timings are illustrative.
The 202 works like a dry cleaner's ticket: the work is accepted, and the ticket is how you ask about it. The comparison breaks on timing, since a dry cleaner does not tell you how long to wait before asking, and a status resource can.
The asynchronous job, step by step
The client submits the job
POST /reports carries the parameters. The server validates them now, so a bad request still gets an immediate 400 rather than a job that fails later.
The server accepts and points at the status
It records job 7, queues it, and answers 202 Accepted with Location: /reports/jobs/7. The body may repeat the link and the initial status, queued. No report is in this response.
The client reads the status
GET /reports/jobs/7 returns 200 with the job's state, running, and a Retry-After: 30 header saying when to ask again.
The worker finishes
In the background the report is built and stored as report 31, and the job is marked succeeded.
The status points at the result
The next read of the job returns 303 See Other with Location: /reports/31. The client follows it and receives the report with an ordinary 200.
The status resource is a resource. It has its own URL, can be read any number of times, and survives the client disconnecting. A client that restarts can carry on from the URL it stored.
202 promises nothing about success. It says the request was accepted for processing. The job may still fail, and the status resource is where the client learns that.
Retries are cheap. If the 202 is lost, the client can resubmit with an idempotency key and receive the same job, rather than starting a second report.
← → move through sections and cards