An API is a product. The users are developers, the interface is code, but all the same product principles apply: it should be intuitive, consistent, and solve a real problem with minimal friction. Most APIs fail at least one of these.

The Principle of Least Surprise

A great API does what you expect. Naming is consistent — if you have getUser and updateUser, you do not also have removeAccount. Error messages tell you what went wrong and how to fix it, not just a status code. Pagination works the same way across every endpoint. Predictability reduces the cognitive load on the consumer.

Design for the 80% Case

The most common operation should be the simplest. If 80% of consumers just need a list of users with basic filters, that call should be one line. The power-user features — complex queries, batch operations, webhook configuration — can have more complexity. Do not burden the simple case with the complexity of the edge case.

Every extra parameter your API requires is a question the consumer has to answer before they can accomplish their goal. Default everything that can be defaulted.

Versioning and Stability

Nothing destroys developer trust faster than a breaking change with no warning. Version your API from day one — even in internal tools. When you need to make a breaking change, deprecate with a timeline, provide a migration guide, and keep the old version running long enough for consumers to migrate. Developer experience is a long game.

Documentation Is Part of the Product

An undocumented API is a broken API. Interactive docs (Swagger, Redoc), runnable examples, and a clear authentication guide are not nice-to-haves — they are the difference between adoption and abandonment. Write the documentation before you ship the endpoint, not after.