hardDesignMidSeniorStaff
One of your endpoints takes four minutes to complete. How should the API expose it?
7 min readUpdated 2026-08-15
Answer
Short answer
Accept the request, return 202 with the location of an operation resource, and do the work behind a queue. Clients poll that resource or receive a signed callback, and either way the operation id is the contract - one that a callback can reach before the submitter has finished recording it.
In a strong api design answer, the how do you expose a long detail should connect the decision to a visible consequence.
Was this answer helpful?
Likely follow-ups
- The callback fires before your client has committed the operation id to its database. What breaks and how do you fix it?
- How do you let a client cancel an operation that has already started?
- Your callbacks to one customer have been failing for six hours. What do you do with the backlog?
- When is holding the connection open with streamed progress the better answer?
Related questions
- Design the contract for a public API. How do you handle pagination, idempotency and versioning?hardAlso on api-design and idempotency7 min
- A customer's bank shows the money left their account and you have no order. How does your checkout make that impossible, and how do you find the ones that already happened?hardAlso on idempotency and webhooks6 min
- Design a notification system that sends 50 million messages a day across email, SMS and push.hardAlso on idempotency5 min
- You must ingest all of English Wikipedia every day, and the source does not want to be hammered. What runs, how often, and what do you do about the run that fails at hour six?hardAlso on idempotency6 min