Part 7 of 12 · 1 min read
How to build it so it holds up
- Return 202 and a job id within milliseconds; do the work elsewhere (module 2).
- Require or strongly support an
Idempotency-Keyon submit; store key, owner, body hash and job id together. - Model states explicitly, enforce legal transitions, make terminal states final.
- Make cancel idempotent and propagate it to the worker (module 3).
- Authorise every read and cancel by owner; use unguessable ids; 404 for not-yours.
- Provide both polling (with Retry-After) and webhooks.
- Sign webhooks, bound the timestamp, dedupe by event id, document retry schedule and when you give up.
- Expose useful status: state, step, partial results, cost so far, timestamps.
- Set a maximum run time and budget per job and report how it ended (Level 9 budgets).
- Version the API and keep old job ids valid.