API design

An API is a promise you cannot withdraw once someone depends on it. Design accordingly: the cost of getting it wrong is paid continuously by everyone who integrates.

Model the domain, not the database

Expose concepts the consumer thinks in. An interface that mirrors internal table structure leaks implementation, breaks whenever storage changes, and forces consumers to reconstruct meaning you already had.

Name things as the domain names them. Consistency in naming, casing, date formats and identifier style matters more than any individual choice being optimal — an interface that is uniformly imperfect is learnable, and one that is inconsistently excellent is not.

Errors are part of the contract

Most integrations spend most of their code on failure. Give it the same care as the success path: