REST API Design Patterns After Building 1,000+ Endpoints

After enough APIs, a few patterns stop being opinions and start being defaults. Consistent resource naming and consistent error shapes across every endpoint save more debugging time than almost anything else — a client integrating against your API should be able to guess the shape of an error before they've seen it.

Versioning from the first endpoint, not the first breaking change, is another one. Retrofitting a version prefix onto an API that mobile apps already depend on is a painful migration that a single early decision avoids entirely.

Pagination, filtering, and sorting need to be designed once, as a shared convention, and then reused everywhere — not reinvented per endpoint. The same goes for authentication: JWT with clear expiry and refresh behavior, documented once, used consistently.

The pattern that didn't survive contact with real usage was building endpoints too specifically for one screen. It's tempting, and it's fast at first, but it means every new screen wants its own endpoint. Designing around resources instead of screens has aged much better across every SaaS product I've built.