RESOURCE MODELING THAT MAKES SENSE
Mistake: endpoints that mirror internal classes. Fix: model around user concepts and stable resources. Guidelines: - Use nouns for resources - Avoid action-heavy endpoints unless needed - Keep relationships clear (nested routes only when it helps) Good APIs read like a product, not like a codebase.
ERRORS THAT HELP, NOT HURT
Mistake: string-only errors and inconsistent status codes. Fix: define a stable error contract: - code (machine-readable) - message (human-readable) - details (field-level issues) - requestId (debug) Also: provide predictable validation errors and avoid hiding problems behind “500”.
PAGINATION, FILTERING, AND SORTING
Mistake: missing pagination or offset-only pagination at scale. Fix: - Cursor pagination for large datasets - Explicit filters (field operators) - Sort rules and defaults Document behavior: max limits, stable ordering, and what happens when data changes between requests.
IDEMPOTENCY & RETRIES
Mistake: unsafe retries that create duplicates. Fix: - Idempotency keys for POST where needed - Safe upserts for “create if not exists” - Clear retry guidance This matters most for payments, provisioning, and jobs/queues.
