Card 09/ 09

RecapDifficulty: Advanced1 min

Recap: Synchronous and Asynchronous APIs

Accept long work quickly, give it a status to check, and send signed events a receiver can safely see twice.

Long work is accepted at once, and its result arrives by polling or by webhook.

  • Synchronous when the work finishes well inside every timeout; asynchronous otherwise.
  • 202 Accepted with Location points at a status resource; it promises acceptance, not success.
  • The status resource reports queued, running, succeeded or failed, sends Retry-After, and 303s to the result.
  • Webhooks are calls to the client's URL, acknowledged with 2xx and retried on failure.
  • Signatures are an HMAC over timestamp and raw body, compared in constant time, with old timestamps refused.
  • Polling works from anywhere; webhooks are prompt but need a reachable receiver.
  • Receivers deduplicate by event id and ignore events older than the state they hold.
The 202 flow and a webhook for the same job