API Design Principles We Follow on Every Project

We've built dozens of APIs across industries, and the ones that succeed share common traits. They're not necessarily the most feature-rich. They are the most predictable and consistent.

Principle 1: Consistency Over Cleverness

Every endpoint should follow the same patterns. If you use camelCase for one response field, use it everywhere. If you paginate one list endpoint with cursor-based pagination, use cursors everywhere. Developers build mental models of your API after using a few endpoints. Inconsistency breaks those models and slows adoption.

Principle 2: Errors Are a Feature

Your error responses are part of your API's user experience. Every error should include: a machine-readable error code, a human-readable message, a pointer to which field or parameter caused the issue, and a link to relevant documentation.

We use RFC 7807 (Problem Details for HTTP APIs) as our standard error format. It's well-specified, widely understood, and gives us a consistent structure to build on.

Principle 3: Version from Day One

API versioning isn't something you add later. It is something you design in from the start. We prefer URL-based versioning (v1/resources) for its simplicity and visibility. Header-based versioning is technically cleaner but causes confusion in practice.

Principle 4: Design for the Unhappy Path

The happy path is easy. Good API design means thinking about: what happens when the database is slow, what happens when a dependent service is down, what happens when the client sends malformed data, and what happens when the client sends valid but nonsensical data.

Every endpoint should have defined behavior for these scenarios, and that behavior should be documented.

Principle 5: Pagination, Filtering, and Sorting

Every list endpoint should support pagination from the start. We use cursor-based pagination for real-time data (where items can be inserted or deleted) and offset-based for static datasets. Filtering should use a consistent query parameter syntax, and sorting should be explicit. Never rely on implicit database ordering.