Practice: An Asynchronous Video Export API

Design the request, the 202, the status resource, a signed webhook and the receiver's checks for a video export.

Designing an asynchronous API means choosing the acceptance, the status resource, the event and the checks that make it trustworthy. A video editing service exports a project to an MP4 file, which takes between one and twenty minutes. Clients are web apps that poll and back-end services that want a webhook. Design:

The request that starts an export, and its response.
The status resource and its states.
The webhook sent when an export ends.
The receiver's checks, in order.

Show a solution

The export API's requests and responses
Step	Request or event	Response or content
Start	POST /projects/12/exports with Idempotency-Key	202 Accepted, Location /exports/88
Check	GET /exports/88	200, status queued or running, progress, Retry-After 30
Done	GET /exports/88	303 See Other, Location /files/501
Failed	GET /exports/88	200, status failed, a problem details error
Webhook	POST to the registered URL	event export.succeeded, event id, export link, signed with timestamp

The receiver's checks, in order: read the timestamp and signature, refuse a timestamp more than five minutes old, compute the HMAC over the timestamp and raw body, compare in constant time, skip an event id already processed, store the event, answer 200, and fetch /exports/88 to act on its current state.

← → move through sections and cards