API platform — composition, idempotency & webhooks
The two API composition styles (gateway aggregation vs GraphQL federation) side by side, with DataLoader batching against N+1, idempotency keys on writes, and signed webhooks with retry.
What this design does
A public API is four disciplines wearing one trench coat: composition (gateway aggregation or a federated graph), write safety (idempotency keys), read efficiency (DataLoader batching so one query doesn't become a hundred), and outbound delivery (webhooks that are signed, replay-protected and retried). This template puts all four on one canvas so the trade-offs stay visible.
The patterns it composes
- API composition (gateway) vs schema federation — aggregate REST at the edge, or compose one graph — per client class
- DataLoader / request batching — N+1 resolver storms collapse into batched fetches
- Idempotency key — write retries are safe by contract
- Webhook signing + retry — HMAC + timestamp beats replays; backoff + DLQ beats flaky receivers
- Rate-limit headers — clients see their budget instead of guessing
Import it, attach your own numbers, and verify the design against failures — or read the engineering notes.