A well-designed API is intuitive to use and hard to misuse. The principles that hold up under real traffic: resource modeling, the idempotency contract behind HTTP methods, status codes that tell the truth, a real error format (RFC 9457), offset vs cursor pagination honestly, versioning strategies and why most are wrong, idempotency keys, and treating the spec as the contract.
Idempotency
-
REST API Design Principles