Imagine an HR portal in a mid-sized Pune company. On the first of each month an administrator clicks “Generate payslips”, and the API call that follows has to build 8,000 PDFs, email links, and write audit rows. In testing with 50 employees it took four seconds. In production it takes about eleven minutes.

The first version simply did all the work inside the request. For the first few months nobody noticed. Then the load balancer’s idle timeout, set to 60 seconds, cut the connection. The browser showed an error. The administrator, naturally, clicked again. Now two payslip jobs were running for the same month, and some employees received two emails.

Everything wrong with that story comes from one design choice: tying the lifetime of the work to the lifetime of a single HTTP connection. Connections drop, proxies time out, phones switch from Wi-Fi to mobile data. Work that matters should not depend on any of them.

Accept now, finish later

The standard fix is to split one call into two ideas: starting the job and learning its outcome. The client sends the request. The server validates it, records a job (an id, a status of “queued”, who asked, the parameters) and replies immediately with HTTP 202 Accepted. The body, or a Location header, points to a status resource such as a job URL.

Behind the scenes a worker, usually fed from a queue, picks the job up and updates its status as it goes: queued, running, succeeded, failed. The API process is free again within milliseconds, and the work survives even if the administrator closes the browser.

Back in the Pune example, the second click now behaves sensibly. The server sees there is already a running payslip job for that month and returns the existing job’s URL (or a 409 Conflict) instead of starting another. This is the same idempotency thinking you use for payments: the client should be able to repeat the request safely.

How the client finds out

There are three common ways, each with a cost.

  • Polling. The client calls the status URL every few seconds. It is simple, works through every firewall, and needs no extra infrastructure. The cost is wasted calls. Good servers include a Retry-After hint so clients do not hammer the endpoint, and clients should slow down progressively rather than ask every second for an hour.
  • Callback (webhook). The client supplies a URL when it starts the job and the server calls it on completion. Efficient, but the client must be reachable from the internet, and you have to handle failed deliveries with retries and signature checks.
  • Push over a persistent connection. WebSockets or server-sent events can stream progress to a browser. Nice for a progress bar, more moving parts to run.

For an internal admin tool, plain polling is usually enough. For partner integrations, offer polling as the baseline and webhooks as the efficient option.

What the status resource should say

While the job is running, a GET on the status URL returns 200 with the state and, if you can compute it, progress, for instance 3,200 of 8,000 done. When it finishes, there are two reasonable patterns. Either the status response includes a link to the result (the generated ZIP, the created resource), or it redirects to it with a 303 See Other. If the job failed, return the failure details in the status body: which stage, which records, whether retrying makes sense. A job failing is not an HTTP error for the status call itself, so the status request still returns 200 and carries “failed” in the body.

Decide early how long results are kept. A report link that works for ever is a storage bill and a privacy risk; a link that expires in an hour annoys people. Seven days is a common, defensible middle for downloadable outputs, though it depends on the data.

Things that bite later

Workers crash. A job marked “running” whose worker died will sit there for ever unless something notices. Use a heartbeat or lease: the worker refreshes a timestamp, and a sweeper requeues jobs whose timestamp is stale. Because a requeued job may run twice, make the work itself safe to repeat, for example by recording “payslip for employee 4712, March” as done and skipping it next time.

Cancellation is another gap. If the administrator started the wrong month, a DELETE on the job URL, or a cancel action, should stop it at the next safe point. Say clearly in the docs what “safe point” means; you cannot un-send emails that have gone out.

Authorisation applies to jobs as well. The job id must not be guessable by someone else’s login; check ownership on every status call, not only on creation.

When this is overkill

If an operation reliably finishes in under a second or two, keep it synchronous. Adding queues and status endpoints to a thing that takes 300 milliseconds buys complexity and nothing else. The signal to switch is when the time grows with data volume, or depends on a slow third party, because then the worst case, not the average, decides whether connections time out. A fair threshold for many teams is “anything that might exceed a few seconds under bad conditions”.

Figures and names in the examples are illustrative.

Leave a Reply

Trending