A good API is not just correct — it is obvious. After building and consuming dozens of APIs, here are the principles that separate the ones engineers love from the ones they tolerate.
The best API I have ever worked with was Stripe's. I built a complete checkout flow from their documentation without once opening a Stack Overflow tab. That is the standard. Most APIs do not meet it.
Principle one: name things for what they do, not what they are. An endpoint called /users/{id}/deactivate is clearer than /users/{id}/status with a PATCH body. The intent is in the URL, not buried in a payload.
Principle two: be consistent above all else. If one endpoint returns created_at, all of them should. If one endpoint uses snake_case, none should use camelCase. Inconsistency forces developers to hold a mental exception map — cognitive overhead that accumulates across every integration.
Principle three: return useful errors. A 400 with the message "Bad Request" helps nobody. A 400 with the message "field 'email' is required, received null" saves the developer ten minutes of debugging and a trip to your documentation.
Principle four: version from day one. The cost of adding /v1/ to every route upfront is zero. The cost of migrating consumers away from an unversioned API is enormous.