API Guides

Practical, opinionated guides on API design patterns. When to use them, when to avoid them, and the trade-offs.

Bulk updates via async jobs Move heavy bulk operations out of the request/response cycle with job resources. Enqueue work, return quickly, let clients poll for status.
bulkjobsidempotencylong-running

intermediate async-operations
Cursor-based pagination for stable lists Use opaque cursors instead of numeric offsets for more stable pagination over changing data like feeds, logs, or events.
paginationcursorsperformance

intro reading-data
Deferred writes with the Outbox Pattern Write events to your database inside the same transaction as your state changes, then publish them reliably with a background worker.
outbox-patterneventsreliabilitytransactionsqueues

intermediate writing-data
Expandable relationships with sparse expansions Avoid over-fetching by default while letting clients pull related data in one call when needed using expand parameters.
relationshipsexpansionsover-fetching

intermediate reading-data
Idempotency keys for safe retries Let clients safely retry non-idempotent calls without accidentally creating duplicates. Essential for payments and critical operations.
idempotencyretriesreliability

intro writing-data
Webhook event delivery with signed payloads Push events to third-party systems in near-real-time with signed payloads, retry logic, and event replay capabilities.
webhookseventssigningsecurity

intermediate integration