api-design-skill

Start from consumer needs and domain behavior, then model resources and operations with stable identifiers and explicit types. Define filtering, sorting, pagination, error codes, and authentication before choosing route names or framework code.

Prefer additive changes that preserve meaning. For breaking changes, inventory consumers, provide a migration path, run old and new contracts in parallel when justified, observe adoption, and define removal criteria before versioning.

Use cursor pagination when collections change during traversal or when offsets become costly at scale. Offset pagination can skip or duplicate items in frequently mutated collections, while cursors remain stable.

Error responses should include stable machine-readable codes, safe user-facing messages, and correlation identifiers for debugging. Never expose stack traces, queries, secrets, or provider internals to consumers.

Specify idempotency, concurrency control, and duplicate handling for each mutation. Use idempotency keys for externally retried operations where duplicate effects would be harmful, such as payment creation.

Webhook design requires schema evolution rules, ordering and replay semantics, signature verification, delivery attempt tracking, deduplication, and consumer lag monitoring to ensure reliable event delivery.