Loading...
Resource modelling, pagination, idempotency, versioning, and backward compatibility.
4 questions in System Design.
Treat errors as published contract: an HTTP status that classifies the failure, a stable machine-readable code the client branches on, a human message that carries no internal detail, per-field detail for validation, and an explicit statement of whether a retry is safe.
Model resources around client workflows, paginate with an opaque keyset cursor because offset pagination skips and duplicates rows under concurrent writes, make unsafe operations replayable with a client-supplied idempotency key, and evolve additively so that versioning stays a last resort rather than a routine.
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.
An idempotency key for retried charges is minted by the client per payment intent, claimed under a unique constraint in the same transaction as the charge, and used to replay the stored response on repeat. The API contract must define retention, in-flight retries and mismatched request bodies.