Most APIs are designed by the team that built the backend, for the team that built the backend. The endpoints mirror internal database tables, the naming follows internal jargon, and the error messages assume you already know how the system works.
This is like designing a consumer product by exposing the factory floor.
Your API is a product
An API has users (developers), a user experience (the integration flow), documentation (the manual), and support costs (tickets filed when something is confusing). It should be designed with the same rigour as any other product.
Contract-first development
We design APIs contract-first. The OpenAPI specification is written, reviewed by actual consumers, and approved before a single line of implementation code exists.
This has three benefits: 1. Consumers validate the design early. If a partner needs an endpoint you did not think of, you find out before you have built the wrong thing. 2. Frontend and backend work in parallel. The spec becomes a mock server on day one. 3. The spec is the documentation. It is always accurate because it is the source of truth, not a document that drifts out of sync with the code.
Consistency matters more than cleverness
A mediocre API that is consistent is better than a brilliant API that surprises you. If one endpoint uses camelCase and another uses snake_case, developers lose trust. If one endpoint returns errors in a different shape than another, every integration needs special-case handling.
Rules we enforce: - One naming convention across every endpoint, field and parameter - One error format with a machine-readable code and a human-readable message - One pagination pattern (cursor-based for lists, not page numbers) - One authentication flow (OAuth 2.0 with clear scope definitions)
Measure adoption, not just uptime
API success metrics should include: - Time to first successful call — how long from reading the docs to a 200 response? - Support tickets per integration — are developers getting stuck? - Adoption rate — are partners actually using it?
99.99% uptime means nothing if nobody wants to integrate.