# Designing an API your customers will not hate

> An API is a product with developers as its users. The ones people enjoy are predictable, honest about errors, and slow to break. A practical guide to the decisions that matter.

*Source: https://www.lazlosoftwaresolution.com/resources/designing-an-api-your-customers-will-not-hate*

If other teams build against your API, it is a product — and its users are developers, who are unusually quick to notice when something is inconsistent or surprising. A good API is not clever. It is predictable, honest when things go wrong, and reluctant to break the code people already wrote against it.

## Be predictable to the point of boring

Consistency beats cleverness everywhere. The same naming, the same shapes, the same patterns across every endpoint. Once a developer learns how one part of your API behaves, they should be able to guess the rest correctly. Every exception to your own conventions is a thing they have to remember.

## Errors are part of the interface

Most of the pain of using an API is in the unhappy path. Return the right status code, a machine-readable error type, and a message a human can act on. "Something went wrong" tells the developer nothing; "the customer_id field is required" tells them exactly what to fix. Good errors are the difference between a five-minute integration and a support ticket.

## Do not break what people already built

The moment someone depends on your API, changing it can break their code without warning. So additions should be safe by default, and breaking changes should go behind a version. Deciding your versioning approach before you have external users is much easier than retrofitting it after you have broken a few of them.

 - Paginate anything that can grow, from the first version — a list that returns everything works until it does not.

 - Make destructive or retryable actions idempotent, so a retried request does not do the thing twice.

 - Rate-limit clearly, and tell callers where they stand in the response.

## Documentation is not optional

An undocumented API is a guessing game, and developers will assume the worst about anything they cannot see. Real examples — actual requests and responses — are worth more than a generated reference, because they show the API being used rather than merely described.

> Developers do not remember the clever endpoint. They remember the one that behaved exactly as they expected, every time.

## The test

Hand your API to a developer who has never seen it, with only the docs, and watch. Where they hesitate, guess wrong, or have to ask is where your design is leaking. Fix those spots and you have an API people are glad to build on.